{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — files Operations"
},
"paths": {
"/rest/files": {
"delete": {
"tags": [
"files"
],
"summary": "Delete files",
"description": "Deletes the specified files. Depending on the system retention policy, the files may be\n recoverable until permanently deleted by the system.\\n\\n**Requires `file_delete` permission\n on the parent folder for each file.**",
"responses": {
"204": {
"description": "Files successfully deleted."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ENTITY_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "id:in",
"description": "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.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "partialSuccess",
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files?id:in=VALUE\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nparams = {\n \"id:in\": \"VALUE\",\n}\nresponse = requests.delete(url, params=params, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/copy": {
"post": {
"summary": "Copy files",
"description": "### Description:\n Copies the specified files to a folder.\n### Precondition:\n Must be assigned the `file_copy` permission for the files being copied and `file_add` permission for the destination folder.\n### Response:\n Copies the files to the folder. If duplicate files exist, appends a number to copied file names.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
},
{
"in": "query",
"name": "id:in",
"required": false,
"explode": true,
"style": "form",
"description": "Comma-separated list of file UUIDs to copy. Cannot be used together with `ids` in the request body.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "If true, successfully copied files are committed even if some files fail to copy.",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileCopyPostBodyRequest"
}
}
}
},
"responses": {
"201": {
"description": "Files have been copied successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ACCESS_DENIED": {
"summary": "Your access is denied.",
"description": "Your access is denied.",
"value": {
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_COPIED_FROM_EC": {
"summary": "Can not perform action on file copied from Repositories Gateway source",
"description": "Can not perform action on file copied from Repositories Gateway source",
"value": {
"errors": [
{
"code": "ERR_ENTITY_COPIED_FROM_EC",
"message": "Can not perform action on file copied from Repositories Gateway source"
}
]
}
},
"ERR_ENTITY_EC_TO_EC": {
"summary": "Unable to copy/move Repositories Gateway file to Repositories Gateway",
"description": "Unable to copy/move Repositories Gateway file to Repositories Gateway",
"value": {
"errors": [
{
"code": "ERR_ENTITY_EC_TO_EC",
"message": "Unable to copy/move Repositories Gateway file to Repositories Gateway"
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
},
"ERR_ENTITY_IS_BASE_DIR": {
"summary": "Operation not permitted on Base Folder",
"description": "Operation not permitted on Base Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
},
"ERR_ENTITY_IS_MY_DIR": {
"summary": "Operation not permitted on Tray Folder",
"description": "Operation not permitted on Tray Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
}
}
}
}
},
"413": {
"description": "Content Too Large
Possible error codes: ERR_SYSTEM_NO_STORAGE_AVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_SYSTEM_NO_STORAGE_AVAILABLE": {
"summary": "Folder owner's remaining storage quota does not permit for a file upload of this size.",
"description": "Folder owner's remaining storage quota does not permit for a file upload of this size.",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_STORAGE_AVAILABLE",
"message": "Folder owner's remaining storage quota does not permit for a file upload of this size."
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/actions/copy\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n ],\n \"destinationFolderId\": \"string\",\n \"replace\": true,\n \"newFileName\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/copy\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n],\n \"destinationFolderId\": \"string\",\n \"replace\": true,\n \"newFileName\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/lock": {
"patch": {
"summary": "Lock files",
"description": "### Description:\n Locks the specified files, preventing others from performing actions such as editing, moving, and deleting the files.\n### Precondition:\n Must be assigned the `lock` permission for the files.\n### Response:\n Locks the files.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "id:in",
"required": false,
"explode": true,
"style": "form",
"description": "A comma-separated list of unique identifier (UUID) of the objects to be processed.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
},
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileLockPostRequest"
}
}
}
},
"responses": {
"200": {
"description": "The files have been successfully locked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkOperationLockFile"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_DLP_LOCKED": {
"summary": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"description": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"value": {
"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."
}
]
}
},
"ERR_ENTITY_IS_ATTACHMENT": {
"summary": "Operation not permitted on attachment",
"description": "Operation not permitted on attachment",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_ATTACHMENT",
"message": "Operation not permitted on attachment"
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/actions/lock\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n ]\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/lock\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n]\n}\nresponse = requests.patch(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/move": {
"post": {
"summary": "Move files",
"description": "### Description:\n Moves the specified files to a folder.\n### Precondition:\n Must be assigned the `file_move` permission for the files being moved and the `file_add` permission for the destination folder.\n### Response:\n Moves the files to the folder.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
},
{
"in": "query",
"name": "id:in",
"required": false,
"explode": true,
"style": "form",
"description": "Comma-separated list of file UUIDs to move. Cannot be used together with `ids` in the request body.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "If true, successfully moved files are committed even if some files fail to move.",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileMovePostBodyRequest"
}
}
}
},
"responses": {
"201": {
"description": "Files have been moved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ACCESS_DENIED": {
"summary": "Your access is denied.",
"description": "Your access is denied.",
"value": {
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_COPIED_FROM_EC": {
"summary": "Can not perform action on file copied from Repositories Gateway source",
"description": "Can not perform action on file copied from Repositories Gateway source",
"value": {
"errors": [
{
"code": "ERR_ENTITY_COPIED_FROM_EC",
"message": "Can not perform action on file copied from Repositories Gateway source"
}
]
}
},
"ERR_ENTITY_EC_TO_EC": {
"summary": "Unable to copy/move Repositories Gateway file to Repositories Gateway",
"description": "Unable to copy/move Repositories Gateway file to Repositories Gateway",
"value": {
"errors": [
{
"code": "ERR_ENTITY_EC_TO_EC",
"message": "Unable to copy/move Repositories Gateway file to Repositories Gateway"
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
},
"ERR_ENTITY_IS_BASE_DIR": {
"summary": "Operation not permitted on Base Folder",
"description": "Operation not permitted on Base Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
},
"ERR_ENTITY_IS_MY_DIR": {
"summary": "Operation not permitted on Tray Folder",
"description": "Operation not permitted on Tray Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
}
}
}
}
},
"413": {
"description": "Content Too Large
Possible error codes: ERR_SYSTEM_NO_STORAGE_AVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_SYSTEM_NO_STORAGE_AVAILABLE": {
"summary": "Folder owner's remaining storage quota does not permit for a file upload of this size.",
"description": "Folder owner's remaining storage quota does not permit for a file upload of this size.",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_STORAGE_AVAILABLE",
"message": "Folder owner's remaining storage quota does not permit for a file upload of this size."
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/actions/move\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n ],\n \"destinationFolderId\": \"string\",\n \"replace\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/move\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n],\n \"destinationFolderId\": \"string\",\n \"replace\": true\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/permanent": {
"delete": {
"tags": [
"files"
],
"summary": "Delete files permanently",
"description": "Permanently deletes the specified files. Files cannot be recovered after this operation.\\n\\n\n **Requires `permanent delete` permission on the parent folder for each file.** Each file must\n already be in the deleted state and must not be locked.",
"responses": {
"204": {
"description": "All specified files permanently deleted."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ENTITY_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "id:in",
"description": "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.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "partialSuccess",
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/actions/permanent?id:in=VALUE\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/permanent\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nparams = {\n \"id:in\": \"VALUE\",\n}\nresponse = requests.delete(url, params=params, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/recover": {
"patch": {
"tags": [
"files"
],
"summary": "Recover deleted files",
"description": "Recovers the specified deleted files, restoring them to their parent folders.\\n\\n**Requires\n `file_recover` permission on the parent folder for each file.** Each file must be in the\n deleted state and must not be permanently deleted.",
"responses": {
"200": {
"description": "Returns the recovered files with their restored status.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"FilesRecovered": {
"summary": "Files successfully recovered",
"value": [
{
"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"
}
]
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "id:in",
"description": "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.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "partialSuccess",
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/actions/recover?id:in=VALUE\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/recover\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nparams = {\n \"id:in\": \"VALUE\",\n}\nresponse = requests.patch(url, params=params, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/scan": {
"post": {
"tags": [
"files"
],
"summary": "Scan files for security",
"description": "Queues security scans for the specified files. Depending on system scan policies, files are\n scanned for anti-virus threats, data loss prevention (DLP) violations, and advanced threat\n protection. Scans run asynchronously.\\n\\n**Requires `view` permission on each file.** Files\n must not be deleted.",
"responses": {
"200": {
"description": "Returns the files for which security scans were queued.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"ScansQueued": {
"summary": "Security scans successfully queued for multiple files",
"value": [
{
"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"
}
]
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "id:in",
"description": "List of IDs of entities to scan. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/actions/scan\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/scan\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/unlock": {
"patch": {
"summary": "Unlock files",
"description": "### Description:\n Unlocks the specified files, enabling others to perform actions such as edit, move, and delete the files.\n### Precondition:\n Must be assigned the `unlock` permission for the files.\n### Response:\n Unlocks the files.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "id:in",
"required": false,
"explode": true,
"style": "form",
"description": "A comma-separated list of unique identifier (UUID) of the objects to be processed.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
},
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileLockPostRequest"
}
}
}
},
"responses": {
"200": {
"description": "The files have been successfully unlocked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkOperationLockFile"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_DLP_LOCKED": {
"summary": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"description": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"value": {
"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."
}
]
}
},
"ERR_ENTITY_IS_ATTACHMENT": {
"summary": "Operation not permitted on attachment",
"description": "Operation not permitted on attachment",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_ATTACHMENT",
"message": "Operation not permitted on attachment"
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/actions/unlock\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n ]\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/unlock\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"ids\": [\n \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n]\n}\nresponse = requests.patch(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/zip": {
"get": {
"tags": [
"files"
],
"summary": "Download files and folders in ZIP format",
"description": "Downloads the specified files and folders as a ZIP archive. Folder contents are included\n recursively. Optionally filtered by file extension.\\n\\n**Requires `download` permission on\n each file and folder.** Files must not be deleted, infected, or DLP-locked.",
"responses": {
"200": {
"description": "Returns a binary ZIP archive containing the requested files and folders."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "name",
"description": "The name for the generated ZIP archive.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "fileId:in",
"description": "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.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "folderId:in",
"description": "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.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "username",
"description": "The email address of the user requesting the ZIP archive.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "extensions",
"description": "Filter files by the specified comma-separated list of extensions.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "utcOffset",
"description": "The user's timezone offset in seconds (e.g., UTC+08:00 = 28800).",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "partialSuccess",
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/actions/zip\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/zip\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/zipStatus": {
"get": {
"summary": "Get file and folder security status",
"description": "### Description:\n Gets the security scan results of specified files and folders in preparation for downloading them in ZIP format.\n### Precondition:\n Must be assigned the `download` permission for the files and folders.\n### Response:\n Returns an empty response if all files are safe for download.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "fileId:in",
"required": false,
"explode": true,
"style": "form",
"description": "A comma-separated list of file IDs (UUID) to check. (Recommended request size <= 100)",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "folderId:in",
"required": false,
"explode": true,
"style": "form",
"description": "A comma-separated list of folder IDs (UUID) to check. (Recommended request size <= 100)",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "Indicates whether the operation should proceed if some files/folders fail the check.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "extensions",
"required": false,
"explode": true,
"style": "form",
"description": "Filter results to include only files with the specified comma-separated list of extensions.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "All files and folders are verified as safe for zipping and download."
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_SYSTEM_TENANT_SUSPENDED": {
"summary": "Access to the service is restricted by the service provider. Contact your administrator for updates on restoring normal access.",
"description": "Access to the service is restricted by the service provider. Contact your administrator for updates on restoring normal access.",
"value": {
"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."
}
]
}
},
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_DLP_LOCKED": {
"summary": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"description": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"value": {
"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."
}
]
}
},
"ERR_ENTITY_DLP_SCANNING": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DLP_SCANNING",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_IS_SECURE_FOLDER": {
"summary": "Operation not permitted on restricted Folder.",
"description": "Operation not permitted on restricted Folder.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_LICENSE_EXPIRED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_LICENSE_EXPIRED": {
"summary": "License has expired",
"description": "License has expired",
"value": {
"errors": [
{
"code": "ERR_LICENSE_EXPIRED",
"message": "License has expired"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/actions/zipStatus\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/zipStatus\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}": {
"get": {
"summary": "Get file metadata",
"description": "### Description:\n Gets metadata for specified files, such as file owner, creation date, digital fingerprint, and security scan status.\n### Precondition:\n Must be assigned the `properties_view` permission for the file.\n### Response:\n Returns the file metadata.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "requirementId",
"required": false,
"description": "UUID of the approval requirement. Required together with `accessVerificationId` to access a file under an approval workflow.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "accessVerificationId",
"required": false,
"description": "UUID of the access verification event. Required together with `requirementId` to validate approver access.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The file has been successfully returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_ACCESS_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_ACCESS_DENIED": {
"summary": "Your access is denied.",
"description": "Your access is denied.",
"value": {
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"post": {
"tags": [
"files"
],
"summary": "Upload a file version",
"description": "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.**",
"responses": {
"200": {
"description": "Returns the updated file record reflecting the newly uploaded version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"New version uploaded": {
"summary": "File record after a new version has been uploaded",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "Binary content of the file",
"type": "string",
"format": "binary"
},
"clientCreated": {
"description": "The date and time when the file was created on the client side.",
"type": "string"
},
"clientModified": {
"description": "The date and time when the file was last modified on the client side.",
"type": "string"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\",\n \"clientCreated\": \"string\",\n \"clientModified\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\",\n \"clientCreated\": \"string\",\n \"clientModified\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
},
"put": {
"summary": "Update a file",
"description": "### Description:\n Updates a file's properties such as name and expiration date.\n### Precondition:\n User must have `properties_edit` permission for the file.\n### Response:\n The file is updated.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "The file has been updated successfully."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ACCESS_DENIED, ERR_ENTITY_DELETED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ACCESS_DENIED": {
"summary": "Your access is denied.",
"description": "Your access is denied.",
"value": {
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"422": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": [
{
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
]
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
]
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
]
}
},
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/files/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"string\",\n \"expire\": \"2024-01-15\",\n \"replace\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"name\": \"string\",\n \"expire\": \"2024-01-15\",\n \"replace\": true\n}\nresponse = requests.put(url, headers=headers, json=payload)\nprint(response.json())"
}
]
},
"delete": {
"tags": [
"files"
],
"summary": "Delete a file",
"description": "Deletes the specified file. Depending on the system retention policy, the file may be\n recoverable until permanently deleted by the system.\\n\\n**Requires `delete` permission on\n the parent folder.** The file must not be locked.",
"responses": {
"204": {
"description": "File successfully deleted."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ENTITY_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file.",
"required": true,
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/lock": {
"patch": {
"tags": [
"files"
],
"summary": "Lock a file",
"description": "Locks the specified file, preventing other users from editing, moving, or deleting it until\n the lock is released.\\n\\n**Requires `lock` permission on the file.** The file must not already\n be locked or deleted.",
"responses": {
"200": {
"description": "Returns the file with its updated lock status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileLocked": {
"summary": "File successfully locked",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ENTITY_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/lock\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/lock\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.patch(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/permanent": {
"delete": {
"summary": "Permanently delete a file",
"description": "### Description:\n Permanently deletes the specified file. The file must have been soft-deleted first.\n### Precondition:\n The user must be the owner, manager, or collaborator of the file.\n The file must not be locked or safe-edit locked, unless the user is an admin.\n The file must have been soft-deleted via `DELETE /rest/files/{id}`.\n### Response:\n The file is permanently deleted and its content cannot be retrieved.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "The file has been permanently deleted."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED, ERR_AUTH_INVALID_CSRF",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
},
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED, ERR_ENTITY_SAFE_EDIT_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": [
{
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
]
}
},
"ERR_ENTITY_SAFE_EDIT_LOCKED": {
"summary": "File is under SafeEDIT by another user",
"description": "File is under SafeEDIT by another user",
"value": {
"errors": [
{
"code": "ERR_ENTITY_SAFE_EDIT_LOCKED",
"message": "File is under SafeEDIT by another user"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/permanent\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/permanent\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/recover": {
"patch": {
"tags": [
"files"
],
"summary": "Recover a file.",
"description": "Recovers the specified deleted file, restoring it to its parent folder.\\n\\n**Requires\n `recover` permission on the parent folder.** The file must be in the deleted state and must\n not be permanently deleted.",
"responses": {
"200": {
"description": "Returns the recovered file with its restored status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileRecovered": {
"summary": "File successfully recovered",
"value": {
"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"
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/recover\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/recover\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.patch(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/return": {
"patch": {
"tags": [
"files"
],
"summary": "Check file into Repositories Gateway source",
"description": "Checks the specified file back into its Repositories Gateway source. The local copy of\n the file is permanently deleted after a successful check-in. If the file is locked in\n the Repositories Gateway source and the caller has `unlock` permission, the lock is\n released automatically.\\n\\n**Requires `view` permission on the parent folder.** The file\n must be eligible to return to source (i.e., it was originally checked out) and must not\n be infected.",
"responses": {
"200": {
"description": "Returns the updated file metadata from the Repositories Gateway source after check-in.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SourceFile"
},
"examples": {
"FileCheckedIn": {
"summary": "File successfully checked back into Repositories Gateway source",
"value": {
"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"
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/return\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/return\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.patch(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/scan": {
"post": {
"tags": [
"files"
],
"summary": "Scan a file for security",
"description": "Queues a security scan for the specified file. Depending on system scan policies, the file\n is scanned for anti-virus threats, data loss prevention (DLP) violations, and advanced threat\n protection. The scan runs asynchronously.\\n\\n**Requires `view` permission on the file.**\n The file must not be deleted.",
"responses": {
"200": {
"description": "Returns the file for which the security scan was queued.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"ScanQueued": {
"summary": "Security scan successfully queued",
"value": {
"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"
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/scan\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/scan\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/unlock": {
"patch": {
"tags": [
"files"
],
"summary": "Unlock a file",
"description": "Unlocks the specified file, allowing other users to edit, move, and delete it.\\n\\n\n **Requires `unlock` permission on the file.** The file must currently be locked.",
"responses": {
"200": {
"description": "Returns the file with its updated lock status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileUnlocked": {
"summary": "File successfully unlocked",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ENTITY_LOCKED_BY_ANOTHER_USER, ERR_ENTITY_UNLOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED_BY_ANOTHER_USER": {
"summary": "File is locked by another user",
"description": "File is locked by another user",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED_BY_ANOTHER_USER",
"message": "File is locked by another user"
}
}
},
"ERR_ENTITY_UNLOCKED": {
"summary": "File is already unlocked",
"description": "File is already unlocked",
"value": {
"errors": {
"code": "ERR_ENTITY_UNLOCKED",
"message": "File is already unlocked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/unlock\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/actions/unlock\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.patch(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/content": {
"get": {
"summary": "Download a file",
"description": "### Description:\n Downloads the specified file.\n### Precondition:\n Must be assigned the `download` permission for the file.\n### Response:\n Downloads the file to the specified location.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "header",
"name": "Range",
"required": false,
"description": "Range of bytes to download. e.g. `bytes=0-1024`",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The file download request was successful.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"206": {
"description": "The file was partially downloaded.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_DLP_LOCKED": {
"summary": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"description": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"value": {
"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."
}
]
}
},
"ERR_ENTITY_IS_SECURE_FOLDER": {
"summary": "Operation not permitted on restricted Folder.",
"description": "Operation not permitted on restricted Folder.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/content\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/content\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/externalEdit": {
"get": {
"tags": [
"files"
],
"summary": "Get access token for external file edit.",
"description": "Retrieves a short-lived refresh token scoped to the specified file, authorizing an external\n editor to download the current version and upload a new version.\\n\\n**Requires `file_add`\n permission on the parent folder.** The file must not be permanently deleted. Users with\n Collaborator, Downloader, or Viewer roles cannot edit files in restricted folders.",
"responses": {
"200": {
"description": "Returns a short-lived refresh token with the scope and expiration required for external file editing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshToken"
},
"examples": {
"ExternalEditToken": {
"summary": "Refresh token for external file editing",
"value": {
"data": [
{
"user_id": 101,
"expire": "2024-06-20T10:05:00Z",
"scope": "GET/files/abc-123/content POST/files/abc-123",
"refresh_token": "rt_xK9mLpQ2nWvZ7rYsT4uA"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/externalEdit\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/externalEdit\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/members": {
"get": {
"summary": "Get users with access to a shared file",
"description": "### Description:\n 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.\n### Precondition:\n File sharing must be activated on the system. Must be assigned the `user_view` permission for the shared file.\n### Response:\n Returns the list of users with access to the shared file, along with metadata about the shared file.\n### Sorting:\n Sort string syntax `FIELD_NAME:ORDER`.\n\n ORDER can be `asc` or `desc`.\n### Sorting options:\n | FIELD_NAME | Description |\n |------------|-------------|\n | id | The member ID |\n | userId | The user ID |\n | groupId | The group ID |\n | roleId | The role ID |\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "userId",
"required": false,
"description": "Filter results by user ID (UUID).",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "groupId",
"required": false,
"description": "Filter results by LDAP group ID.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "roleId",
"required": false,
"description": "Filter results by role ID.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "userId:in",
"required": false,
"explode": true,
"style": "form",
"description": "Filter by a comma-separated list of user IDs (UUID). (Recommended request size <= 100)",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "groupId:in",
"required": false,
"explode": true,
"style": "form",
"description": "Filter by a comma-separated list of LDAP Group IDs. (Recommended request size <= 100)",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "roleId:in",
"required": false,
"explode": true,
"style": "form",
"description": "Filter by a comma-separated list of role IDs.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "type",
"required": false,
"description": "Filter members by the object type they have access to.
`f` – File membership.
`d` – Directory (folder) membership.",
"schema": {
"type": "string",
"enum": [
"d",
"f"
]
}
},
{
"in": "query",
"name": "orderBy",
"required": false,
"description": "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`.",
"schema": {
"type": "string",
"enum": [
"id:asc",
"id:desc",
"userId:asc",
"userId:desc",
"groupId:asc",
"groupId:desc",
"roleId:asc",
"roleId:desc",
"rank:asc",
"rank:desc",
"email:asc",
"email:desc"
]
}
},
{
"in": "query",
"name": "limit",
"required": false,
"description": "Range limit.",
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"in": "query",
"name": "offset",
"required": false,
"description": "Range offset.",
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
}
],
"responses": {
"200": {
"description": "The file members have been successfully returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Members"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_JSON",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_JSON": {
"summary": "Invalid json provided",
"description": "Invalid json provided",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_JSON",
"message": "Invalid json provided"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_SYSTEM_TENANT_SUSPENDED, ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_USER_TYPE_NO_ACCESS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_SYSTEM_TENANT_SUSPENDED": {
"summary": "Access to the service is restricted by the service provider. Contact your administrator for updates on restoring normal access.",
"description": "Access to the service is restricted by the service provider. Contact your administrator for updates on restoring normal access.",
"value": {
"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."
}
]
}
},
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_USER_TYPE_NO_ACCESS": {
"summary": "Permission denied",
"description": "Permission denied",
"value": {
"errors": [
{
"code": "ERR_USER_TYPE_NO_ACCESS",
"message": "Permission denied"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_LICENSE_EXPIRED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_LICENSE_EXPIRED": {
"summary": "License has expired",
"description": "License has expired",
"value": {
"errors": [
{
"code": "ERR_LICENSE_EXPIRED",
"message": "License has expired"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"delete": {
"summary": "Remove all access to a shared file",
"description": "### Description:\n Removes user access to the specified shared file.\n### Precondition:\n Must be assigned the `user_add` permission for the folder containing the shared file.\n### Response:\n Removes user access to the shared file.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "All file members have been successfully removed."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/members/ldapGroup": {
"get": {
"tags": [
"files"
],
"summary": "List LDAP groups with access to a shared file",
"description": "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.",
"responses": {
"200": {
"description": "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.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemberGroup"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"FileGroupList": {
"summary": "A page of LDAP group access grants",
"value": [
{
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 3
}
]
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "ID of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "groupId",
"description": "The unique identifier of the group.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "groupId:in",
"description": "The unique identifier of the group.. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "roleId",
"description": "The unique identifier of the role.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "roleId:in",
"description": "The unique identifier of the role.. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "orderBy",
"description": "Sorting options",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"id:asc",
"id:desc",
"groupId:asc",
"groupId:desc",
"roleId:asc",
"roleId:desc"
]
}
},
{
"in": "query",
"name": "offset",
"description": "Offset",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"description": "Limit",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members/ldapGroup\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # ID of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members/ldapGroup\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/members/ldapGroup/{ldap_group_id}": {
"get": {
"tags": [
"files"
],
"summary": "Get a specific LDAP group's access to a shared file",
"description": "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.",
"responses": {
"200": {
"description": "Returns the access grant record for the specified LDAP group, including its assigned role for the file's folder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemberGroup"
},
"examples": {
"FileGroupMember": {
"summary": "LDAP group with viewer role",
"value": {
"objectId": "abc12345def67890ab",
"groupId": 42,
"roleId": 4
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "ID of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "ldap_group_id",
"description": "The unique identifier of the LDAP group.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members/ldapGroup/:ldap_group_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # ID of the file\nldap_group_id = \"VALUE\" # The unique identifier of the LDAP group.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members/ldapGroup/{ldap_group_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/members/{member_user_id}": {
"get": {
"tags": [
"files"
],
"summary": "Returns the specified user member associated with the file.",
"description": "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.",
"responses": {
"200": {
"description": "Returns the specified user member and their role for the file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Member"
},
"examples": {
"FileMember": {
"summary": "User member with viewer role",
"value": {
"objectId": "abc12345def67890ab",
"userId": "usr98765cba43210fe",
"roleId": 4
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "member_user_id",
"description": "The unique identifier of the user member.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members/:member_user_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file.\nmember_user_id = \"VALUE\" # The unique identifier of the user member.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members/{member_user_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"put": {
"summary": "Update file member",
"description": "### Description:\n Changes the role assigned to the specified user for accessing the specified shared file.\n### Precondition:\n Must be assigned the `user_add` permission for the folder containing the file.\n### Response:\n Changes the user's role to the specified role.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "path",
"name": "member_user_id",
"required": true,
"description": "The unique identifier (UUID) of the user.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The file member's role has been successfully updated."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_IS_BASE_DIR": {
"summary": "Operation not permitted on Base Folder",
"description": "Operation not permitted on Base Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
},
"ERR_ENTITY_IS_MY_DIR": {
"summary": "Operation not permitted on Tray Folder",
"description": "Operation not permitted on Tray Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
},
"ERR_ENTITY_IS_SYNC_DIR": {
"summary": "Operation not permitted on My Folder",
"description": "Operation not permitted on My Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SYNC_DIR",
"message": "Operation not permitted on My Folder"
}
]
}
},
"ERR_ENTITY_IS_SECURE_FOLDER": {
"summary": "Operation not permitted on restricted Folder.",
"description": "Operation not permitted on restricted Folder.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
},
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_ENTITY_EXISTS, ERR_ENTITY_ROLE_IS_ASSIGNED, ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
},
"ERR_ENTITY_ROLE_IS_ASSIGNED": {
"summary": "Cannot assign already assigned role",
"description": "Cannot assign already assigned role",
"value": {
"errors": [
{
"code": "ERR_ENTITY_ROLE_IS_ASSIGNED",
"message": "Cannot assign already assigned role"
}
]
}
},
"ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS": {
"summary": "Target user has insufficient access permissions",
"description": "Target user has insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"message": "Target user has insufficient access permissions"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members/:member_user_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\nmember_user_id = \"VALUE\" # The unique identifier (UUID) of the user.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members/{member_user_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.put(url, headers=headers)\nprint(response.json())"
}
]
},
"delete": {
"summary": "Remove a user's access to a shared file",
"description": "### Description:\n Removes the specified user's access to the specified shared file.\n### Precondition:\n Must be assigned the `user_add` permission for the folder containing the shared file.\n### Response:\n Removes the user's access to the shared file.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "path",
"name": "member_user_id",
"required": true,
"description": "The unique identifier (UUID) of the user.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The member has been successfully removed from the file."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members/:member_user_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\nmember_user_id = \"VALUE\" # The unique identifier (UUID) of the user.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members/{member_user_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/path": {
"get": {
"tags": [
"files"
],
"summary": "Get file path",
"description": "Returns the full ancestor path of the specified file, from the workspace root down to the\n file's parent folder. Each element in the path represents a folder node with its ID and\n name.\\n\\n**Requires `properties_view` permission on the file.**",
"responses": {
"200": {
"description": "Returns the full ancestor path of the file as an ordered list of folder nodes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FilePathResponse"
},
"examples": {
"FilePathSuccess": {
"summary": "Full path to a file nested two levels deep",
"value": {
"data": [
{
"id": "1",
"name": "My Workspace"
},
{
"id": "3",
"name": "Documents"
}
],
"links": [
{
"rel": "self",
"href": "https:///rest/1.0/files/9/path"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/path\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/path\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/preview": {
"get": {
"summary": "Get file preview metadata",
"description": "### Description:\n Gets file preview metadata about the specified file, such as the permalink for previewing the file and if the file contains a watermark.\n### Precondition:\n Must be assigned the `view` permission for the file.\n### Response:\n Returns the file preview metadata.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The file preview information has been successfully returned."
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ACCESS_DENIED, ERR_ENTITY_DELETED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ACCESS_DENIED": {
"summary": "Your access is denied.",
"description": "Your access is denied.",
"value": {
"errors": [
{
"code": "ERR_ACCESS_DENIED",
"message": "Your access is denied.",
"redirectUrl": "/login?code=3317"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/preview\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/preview\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/tasks": {
"get": {
"tags": [
"files",
"tasks"
],
"summary": "Get file tasks",
"description": "Gets a list of tasks assigned to the specified file. **Requires `task_view` permission on the file's parent folder.**",
"responses": {
"200": {
"description": "Returns a paginated list of tasks associated with the specified file.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"File task list": {
"summary": "A paginated list of tasks for a file",
"value": {
"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
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "assigneeId",
"description": "Assigned User unique identifier",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "assigneeId:in",
"description": "Assigned User unique identifier. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "due",
"description": "Task due date",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "due:gt",
"description": "Task due date. Search for results where this parameter value is greater than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "due:gte",
"description": "Task due date. Search for results where this parameter value is greater than or equal to the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "due:lt",
"description": "Task due date. Search for results where this parameter value is less than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "due:lte",
"description": "Task due date. Search for results where this parameter value is less than or equal to the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "parentId",
"description": "Parent Comment identifier",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "parentId:in",
"description": "Parent Comment identifier. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "userId",
"description": "Identifier of User who created a Task",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "userId:in",
"description": "Identifier of User who created a Task. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "created",
"description": "Task creation date",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:gt",
"description": "Task creation date. Search for results where this parameter value is greater than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:gte",
"description": "Task creation date. Search for results where this parameter value is greater than or equal to the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:lt",
"description": "Task creation date. Search for results where this parameter value is less than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:lte",
"description": "Task creation date. Search for results where this parameter value is less than or equal to the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "modified",
"description": "Task modification date",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "modified:gt",
"description": "Task modification date. Search for results where this parameter value is greater than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "modified:gte",
"description": "Task modification date. Search for results where this parameter value is greater than or equal to the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "modified:lt",
"description": "Task modification date. Search for results where this parameter value is less than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "modified:lte",
"description": "Task modification date. Search for results where this parameter value is less than or equal to the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "contents:contains",
"description": "Task content. Search for results that contain the specified characters in this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "status",
"description": "Filter tasks by status. Accepted values: `D`, `P`, `C`.",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"D",
"P",
"C"
]
}
},
{
"in": "query",
"name": "deleted",
"description": "Whether the task has been deleted",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "orderBy",
"description": "Sorting options",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"id:asc",
"id:desc",
"due:asc",
"due:desc",
"created:asc",
"created:desc",
"modified:asc",
"modified:desc"
]
}
},
{
"in": "query",
"name": "offset",
"description": "Offset",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"description": "Limit",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/tasks\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/tasks\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"post": {
"tags": [
"files",
"tasks"
],
"summary": "Create file task",
"description": "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.**",
"responses": {
"200": {
"description": "Returns the newly created task record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task"
},
"examples": {
"Task created": {
"summary": "A newly created task assigned to a user",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_REQUIRED, ERR_INPUT_DATE_NOT_AFTER, ERR_INPUT_HTML_TAGS_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_REQUIRED": {
"summary": "Field is required",
"description": "Field is required",
"value": {
"errors": {
"code": "ERR_INPUT_REQUIRED",
"message": "Field is required"
}
}
},
"ERR_INPUT_HTML_TAGS_INVALID": {
"summary": "Cannot contain HTML tags other than B, I, or U",
"description": "Cannot contain HTML tags other than B, I, or U",
"value": {
"errors": {
"code": "ERR_INPUT_HTML_TAGS_INVALID",
"message": "Cannot contain HTML tags other than B, I, or U"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "Object ID of the file task is created on",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task.Post"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id/tasks\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"assigneeId\": 1,\n \"due\": \"2024-01-15\",\n \"parentId\": 1,\n \"contents\": \"string\",\n \"addLinks\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # Object ID of the file task is created on\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/tasks\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"assigneeId\": 1,\n \"due\": \"2024-01-15\",\n \"parentId\": 1,\n \"contents\": \"string\",\n \"addLinks\": true\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/versions": {
"get": {
"tags": [
"files"
],
"summary": "Get file versions",
"description": "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.**",
"responses": {
"200": {
"description": "Returns a paginated list of version records for the specified file.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Version"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"Version list": {
"summary": "A paginated list of two file versions",
"value": {
"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
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "created",
"description": "File Version creation date",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "created:gt",
"description": "File Version creation date. Search for results where this parameter value is greater than the specified value.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "created:gte",
"description": "File Version creation date. Search for results where this parameter value is greater than or equal to the specified value.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "created:lt",
"description": "File Version creation date. Search for results where this parameter value is less than the specified value.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "created:lte",
"description": "File Version creation date. Search for results where this parameter value is less than or equal to the specified value.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "orderBy",
"description": "Sorting options",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"id:asc",
"id:desc",
"versionNumber:asc",
"versionNumber:desc",
"created:asc",
"created:desc"
]
}
},
{
"in": "query",
"name": "offset",
"description": "Offset",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"description": "Limit",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "locate_id",
"description": "If specified, \"offset\" parameter will be ignored\n and the page containing entity with this Id will be returned.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"post": {
"tags": [
"files"
],
"summary": "Upload a file version",
"description": "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.",
"responses": {
"200": {
"description": "New file version uploaded successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileVersionCreated": {
"summary": "File after new version upload",
"value": {
"id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
"name": "document.pdf",
"type": "file",
"size": 307200,
"modified": "2024-03-02T09:30:00+00:00"
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_ENTITY_EXISTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": {
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the file (UUID) to which the version is being uploaded.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "The binary content of the file.",
"type": "string",
"format": "binary"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the file (UUID) to which the version is being uploaded.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/versions/{version_id}": {
"get": {
"tags": [
"files"
],
"summary": "Get a file version",
"description": "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.**",
"responses": {
"200": {
"description": "Returns the metadata for the specified file version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Version"
},
"examples": {
"Version metadata": {
"summary": "Metadata for a single file version",
"value": {
"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": []
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the file.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "version_id",
"description": "The unique identifier (UUID) of the file version.",
"required": true,
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the file.\nversion_id = \"VALUE\" # The unique identifier (UUID) of the file version.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"delete": {
"tags": [
"files"
],
"summary": "Delete a file version",
"description": "Deletes the specified version of the file. Cannot delete the last remaining version of a file. **Requires `version_delete` permission on the file.**",
"responses": {
"204": {
"description": "The version was successfully deleted. Returns no content."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
},
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the file.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "version_id",
"description": "The unique identifier (UUID) of the file version.",
"required": true,
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the file.\nversion_id = \"VALUE\" # The unique identifier (UUID) of the file version.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/versions/{version_id}/actions/promote": {
"post": {
"tags": [
"files"
],
"summary": "Promote a file version",
"description": "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.**",
"responses": {
"200": {
"description": "Returns the promoted version record after it has been set as the current version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Version"
},
"examples": {
"Version promoted": {
"summary": "The specified version is now the current version",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_LOCKED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
},
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "version_id",
"description": "The unique identifier (UUID) of the file version.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/actions/promote\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of file\nversion_id = \"VALUE\" # The unique identifier (UUID) of the file version.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/actions/promote\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/versions/{version_id}/actions/scan": {
"post": {
"tags": [
"files"
],
"summary": "Scan a file version for security",
"description": "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.**",
"responses": {
"200": {
"description": "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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Version"
},
"examples": {
"Scan triggered": {
"summary": "Scan triggered; version returned with current scan state",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "version_id",
"description": "The unique identifier (UUID) of the file version.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/actions/scan\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of file\nversion_id = \"VALUE\" # The unique identifier (UUID) of the file version.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/actions/scan\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/versions/{version_id}/content": {
"get": {
"tags": [
"files"
],
"summary": "Download a file version",
"description": "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.",
"responses": {
"200": {
"description": "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": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "version_id",
"description": "The unique identifier (UUID) of the file version.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Range",
"description": "Range of bytes to download. e.g. `bytes=0-1024`",
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/content\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of file\nversion_id = \"VALUE\" # The unique identifier (UUID) of the file version.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/content\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/versions/{version_id}/preview": {
"get": {
"tags": [
"files"
],
"summary": "Get file preview metadata for a file version",
"description": "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.**",
"responses": {
"200": {
"description": "Returns the preview metadata for the specified file version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Preview"
},
"examples": {
"Preview ready": {
"summary": "Preview is available",
"value": {
"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
}
},
"Preview processing": {
"summary": "Preview is still being generated",
"value": {
"link": null,
"pdf": null,
"view_url": null,
"status": "Processing",
"mime": null,
"native": false,
"watermark": null,
"tdfOriginalExtension": null
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the file.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "version_id",
"description": "The unique identifier (UUID) of the file version.",
"required": true,
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/:id/versions/:version_id/preview\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the file.\nversion_id = \"VALUE\" # The unique identifier (UUID) of the file version.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/versions/{version_id}/preview\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/folders/{id}/actions/file": {
"post": {
"tags": [
"files"
],
"summary": "Upload a file using multipart form data",
"description": "Uploads a file to the specified folder using multipart form data. If a file with the same\n name already exists, a new version is created unless `disableAutoVersion` is set.\\n\\n\n **Requires `file_add` permission on the target folder** (or `version_create` if a file with\n the same name already exists). The folder must not be deleted. Sufficient storage must be\n available. The file extension and MIME type must not be excluded by the system policy.",
"responses": {
"200": {
"description": "Returns the uploaded file metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileUploaded": {
"summary": "File successfully uploaded",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_ENTITY_EXISTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": {
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the target folder.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "The binary content of the file.",
"type": "string",
"format": "binary"
},
"clientCreated": {
"description": "The date and time when the file was created on the client side.",
"type": "string"
},
"clientModified": {
"description": "The date and time when the file was last modified on the client side.",
"type": "string"
},
"disableAutoVersion": {
"description": "Indicates if the file should be prevented from being saved as a new version.",
"type": "boolean"
},
"note": {
"description": "Indicates if the file should be uploaded as a note.",
"type": "boolean"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/folders/:id/actions/file\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\",\n \"clientCreated\": \"string\",\n \"clientModified\": \"string\",\n \"disableAutoVersion\": true,\n \"note\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the target folder.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/file\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\",\n \"clientCreated\": \"string\",\n \"clientModified\": \"string\",\n \"disableAutoVersion\": true,\n \"note\": true\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/folders/{id}/actions/fileBase64Encoded": {
"post": {
"tags": [
"files"
],
"summary": "Upload a base64-encoded file",
"description": "Uploads a base64-encoded file to the specified folder. If a file with the same name already\n exists, a new version is created unless `disableAutoVersion` is set.\\n\\n**Requires\n `file_add` permission on the target folder** (or `version_create` if a file with the same\n name already exists). The file content must be valid base64. The file size must not exceed\n the system-configured upload size limit. The file extension must not be excluded by the\n system policy.",
"responses": {
"200": {
"description": "Returns the uploaded file metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileUploaded": {
"summary": "Base64-encoded file successfully uploaded",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_ENTITY_EXISTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": {
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier (UUID) of the target folder.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Content.Post"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/folders/:id/actions/fileBase64Encoded\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"addLinks\": true,\n \"name\": \"string\",\n \"content\": \"string\",\n \"clientCreated\": 1,\n \"clientModified\": 1,\n \"note\": 1\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the target folder.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/fileBase64Encoded\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"addLinks\": true,\n \"name\": \"string\",\n \"content\": \"string\",\n \"clientCreated\": 1,\n \"clientModified\": 1,\n \"note\": 1\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/folders/{parent_id}/actions/fileFromTemplate": {
"post": {
"tags": [
"files"
],
"summary": "Create Microsoft Office document from template",
"description": "Creates a new, blank Microsoft Office document from a template in the specified folder.\\n\\n\n **Requires `file_add` permission on the target folder.** The folder must not be deleted.\n The file name must not contain invalid characters.",
"responses": {
"200": {
"description": "Returns the newly created file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileCreatedFromTemplate": {
"summary": "Blank Word document created from template",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
},
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "parent_id",
"description": "ID of the parent folder",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileNameRequest.Post"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/folders/:parent_id/actions/fileFromTemplate\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fileType\": \"string\",\n \"fileName\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nparent_id = \"VALUE\" # ID of the parent folder\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/folders/{parent_id}/actions/fileFromTemplate\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"fileType\": \"string\",\n \"fileName\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/folders/{parent}/files": {
"post": {
"tags": [
"files"
],
"summary": "Upload a file",
"description": "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.",
"responses": {
"200": {
"description": "File uploaded successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileCreated": {
"summary": "Newly uploaded file",
"value": {
"id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
"name": "document.pdf",
"type": "file",
"size": 204800,
"modified": "2024-03-01T12:00:00+00:00"
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_LOCKED": {
"summary": "File is locked",
"description": "File is locked",
"value": {
"errors": {
"code": "ERR_ENTITY_LOCKED",
"message": "File is locked"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_ENTITY_EXISTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": {
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "parent",
"description": "The unique identifier (UUID) of the target folder.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-KW-Note",
"description": "Indicates if the file should be uploaded as a note.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "The binary content of the file.",
"type": "string",
"format": "binary"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/folders/:parent/files\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nparent = \"VALUE\" # The unique identifier (UUID) of the target folder.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/folders/{parent}/files\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/permissions/file/{file_id}": {
"get": {
"tags": [
"files",
"permissions"
],
"summary": "Get file permissions",
"description": "Returns the list of actions the current user is allowed to perform on the specified file, such as downloading, editing, or commenting.",
"responses": {
"200": {
"description": "File permissions retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
}
}
},
"examples": {
"FilePermissions": {
"summary": "Permissions available on a file",
"value": {
"data": [
{
"id": "DOWNLOAD",
"name": "Download",
"allowed": true
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "file_id",
"description": "ID of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "id",
"description": "Unique action identifier",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "id:in",
"description": "Unique action identifier. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "name",
"description": "Action name",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "name:contains",
"description": "Action name. Search for results that contain the specified characters in this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "allowed",
"description": "Determines if one has permissions to perform action",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "enabled",
"description": "Determines if the given action is available considering the current object state (locked, deleted, etc.).",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/permissions/file/:file_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nfile_id = \"VALUE\" # ID of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/permissions/file/{file_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/permissions/files": {
"get": {
"tags": [
"files",
"permissions"
],
"summary": "Get file permissions for a set of files",
"description": "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.",
"responses": {
"200": {
"description": "File permissions retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FilePermissions"
}
}
}
},
"examples": {
"BulkFilePermissions": {
"summary": "Permissions for a set of files",
"value": {
"data": [
{
"fileId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"permissions": [
{
"id": "DOWNLOAD",
"name": "Download",
"allowed": true
}
]
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "id:in",
"description": "Unique identifier of the file.. Search for results that match any of the specified values for this parameter.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "name",
"description": "Action name",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "name:contains",
"description": "Action name. Search for results that contain the specified characters in this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "allowed",
"description": "Determines if one has permissions to perform action",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "enabled",
"description": "Determines if the given action is available considering the current object state (locked, deleted, etc.).",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "action_id",
"description": "Unique action identifier",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "action_id:in",
"description": "Unique action identifier. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "with",
"description": "With parameters",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full",
"compact"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/permissions/files?id:in=VALUE\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/permissions/files\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nparams = {\n \"id:in\": \"VALUE\",\n}\nresponse = requests.get(url, params=params, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/requestFile/{ref}/actions/file": {
"post": {
"tags": [
"files",
"requestFile"
],
"summary": "Upload a file requested by user",
"description": "Uploads a file to a folder or inbox in response to a file request from another user.\n Access is granted via the request file reference link (`ref`). If the request requires\n authentication (`require_auth`), the caller must be logged in. The uploaded file is\n renamed to include the uploader's email address.\\n\\nThe request link must not be expired\n or have reached its upload limit. Sufficient storage must be available in the target\n folder. The file extension and MIME type must not be excluded by the requestor's system\n policy.",
"responses": {
"200": {
"description": "Returns the uploaded file metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
},
"examples": {
"FileUploaded": {
"summary": "File successfully uploaded in response to a file request",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "ref",
"description": "The unique reference of the Request File upload link.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "The binary content of the file.",
"type": "string",
"format": "binary"
},
"clientCreated": {
"description": "The date and time when the file was created on the client side.",
"type": "string"
},
"clientModified": {
"description": "The date and time when the file was last modified on the client side.",
"type": "string"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/requestFile/:ref/actions/file\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\",\n \"clientCreated\": \"string\",\n \"clientModified\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nref = \"VALUE\" # The unique reference of the Request File upload link.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/actions/file\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\",\n \"clientCreated\": \"string\",\n \"clientModified\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/requestFile/{ref}/comment/{object_id}": {
"post": {
"tags": [
"files",
"requestFile"
],
"summary": "Add a comment to an uploaded file",
"description": "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.",
"responses": {
"200": {
"description": "Returns the newly created comment record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Comment"
},
"examples": {
"Comment created": {
"summary": "A comment added to an uploaded file",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_MAX_VALUE, ERR_INPUT_HTML_TAGS_INVALID, ERR_INPUT_REQUIRED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_HTML_TAGS_INVALID": {
"summary": "Cannot contain HTML tags other than B, I, or U",
"description": "Cannot contain HTML tags other than B, I, or U",
"value": {
"errors": {
"code": "ERR_INPUT_HTML_TAGS_INVALID",
"message": "Cannot contain HTML tags other than B, I, or U"
}
}
},
"ERR_INPUT_REQUIRED": {
"summary": "Field is required",
"description": "Field is required",
"value": {
"errors": {
"code": "ERR_INPUT_REQUIRED",
"message": "Field is required"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "ref",
"description": "The unique reference of the Request File upload link.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "object_id",
"description": "Object ID of the file being commented on.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Comment.Post"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/requestFile/:ref/comment/:object_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"parentId\": 1,\n \"contents\": \"string\",\n \"addLinks\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nref = \"VALUE\" # The unique reference of the Request File upload link.\nobject_id = \"VALUE\" # Object ID of the file being commented on.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/comment/{object_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"parentId\": 1,\n \"contents\": \"string\",\n \"addLinks\": true\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/requestFile/{ref}/sources/{object_id}/content": {
"get": {
"tags": [
"files",
"requestFile"
],
"summary": "Download files from folder in request files to folder message",
"description": "Downloads a file that was made available to recipients as a source attachment in a\n request files to folder message. Access is granted via the request file reference link\n (`ref`).\\n\\nThe request link must be valid and not expired. If the request requires\n authentication, the caller must be logged in. The file must not be deleted, infected,\n or DLP-locked.",
"responses": {
"200": {
"description": "Returns the binary file content as a downloadable stream."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "ref",
"description": "The unique reference of the Request File upload link.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "object_id",
"description": "The unique identifier of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Range",
"description": "Range of bytes to download. e.g. `bytes=0-1024`",
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/requestFile/:ref/sources/:object_id/content\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nref = \"VALUE\" # The unique reference of the Request File upload link.\nobject_id = \"VALUE\" # The unique identifier of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/sources/{object_id}/content\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/requestFile/{ref}/uploads/{object_id}/content": {
"get": {
"tags": [
"files",
"requestFile"
],
"summary": "Download files uploaded to request files to folder or inbox message",
"description": "Downloads a file that was uploaded to a request files to folder or inbox message. Access\n is granted via the request file reference link (`ref`).\\n\\n**Authentication is required**\n — guest access is not permitted for this endpoint. The file must be associated with the\n specified request link, must not be deleted, and must not be infected or DLP-locked.",
"responses": {
"200": {
"description": "Returns the binary file content as a downloadable stream."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "ref",
"description": "The unique reference of the Request File upload link.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "object_id",
"description": "The unique identifier of the file",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Range",
"description": "Range of bytes to download. e.g. `bytes=0-1024`",
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/requestFile/:ref/uploads/:object_id/content\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nref = \"VALUE\" # The unique reference of the Request File upload link.\nobject_id = \"VALUE\" # The unique identifier of the file\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/requestFile/{ref}/uploads/{object_id}/content\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/sources/actions/downloadByTransaction": {
"get": {
"tags": [
"files"
],
"summary": "Download a file from Repositories Gateway source by transaction ID",
"description": "Downloads a file from its Repositories Gateway source using the transaction ID obtained\n from `POST /sources/{id}/actions/initiateDownload`. The transfer must have completed\n successfully before calling this endpoint.\\n\\n**Requires `download` permission on the\n file.**",
"responses": {
"200": {
"description": "Returns the binary file content as a downloadable stream."
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "transactionId",
"description": "Transaction ID of download",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/sources/actions/downloadByTransaction\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/sources/actions/downloadByTransaction\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/sources/actions/files/{id}": {
"post": {
"tags": [
"files"
],
"summary": "Upload a file version to Repositories Gateway source",
"description": "Uploads a new version of the specified file to its Repositories Gateway source. Returns a\n transfer status record reflecting the result of the upload operation.\\n\\n**Requires\n `file_add` permission on the Repositories Gateway parent folder of the file.** The file\n extension and MIME type must not be excluded by the system policy.",
"responses": {
"200": {
"description": "Returns the transfer status record for the upload operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KPTransferStatus"
},
"examples": {
"VersionUploaded": {
"summary": "New file version successfully uploaded to Repositories Gateway source",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the Repositories Gateway file to add a new version to.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "The binary content of the file.",
"type": "string",
"format": "binary"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/sources/actions/files/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the Repositories Gateway file to add a new version to.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/sources/actions/files/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/sources/{id}/actions/file": {
"post": {
"tags": [
"files"
],
"summary": "Upload a file to Repositories Gateway source",
"description": "Uploads a file to the specified Repositories Gateway source folder. Returns a transfer\n status record that reflects the result of the upload operation.\\n\\n**Requires `file_add`\n permission on the target Repositories Gateway folder.** The file extension and MIME type\n must not be excluded by the system policy.",
"responses": {
"200": {
"description": "Returns the transfer status record for the upload operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KPTransferStatus"
},
"examples": {
"FileUploaded": {
"summary": "File successfully uploaded to Repositories Gateway source",
"value": {
"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": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_RESTRICTED_EXTENSION": {
"summary": "File extension is in exclusion extensions list",
"description": "File extension is in exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM": {
"summary": "File extension is in custom exclusion extensions list",
"description": "File extension is in custom exclusion extensions list",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_EXTENSION_CUSTOM",
"message": "File extension is in custom exclusion extensions list"
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE": {
"summary": "The specified entity mime type is not allowed.",
"description": "The specified entity mime type is not allowed.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_CUSTOM": {
"summary": "The specified file type is in custom excluded file types list.",
"description": "The specified file type is in custom excluded file types list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_CUSTOM",
"message": "The specified file type is in custom excluded file types list."
}
}
},
"ERR_ENTITY_RESTRICTED_TYPE_GROUP": {
"summary": "File mime type is in exclusion groups list.",
"description": "File mime type is in exclusion groups list.",
"value": {
"errors": {
"code": "ERR_ENTITY_RESTRICTED_TYPE_GROUP",
"message": "File mime type is in exclusion groups list."
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the Repositories Gateway target folder.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "returnEntity",
"description": "If set to `true`, returns information about the newly created entity.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "mode",
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"body": {
"description": "The binary content of the file.",
"type": "string",
"format": "binary"
}
},
"required": [
"body"
]
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/sources/:id/actions/file\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"body\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the Repositories Gateway target folder.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/sources/{id}/actions/file\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"body\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/sources/{id}/actions/initiateDownload": {
"post": {
"tags": [
"files"
],
"summary": "Download a file asynchronously from Repositories Gateway source",
"description": "Initiates an asynchronous download of the specified file from its Repositories Gateway\n source. Returns a transfer status record that can be polled via\n `GET /sources/actions/downloadByTransaction` until the transfer completes.\\n\\n\n **Requires `download` permission on the file.**",
"responses": {
"200": {
"description": "Returns the transfer status record for the initiated download, including the transaction ID used to poll for completion.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KPTransferStatus"
},
"examples": {
"DownloadInitiated": {
"summary": "Asynchronous download successfully initiated",
"value": {
"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": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the file from Repositories Gateway Source.",
"required": true,
"schema": {
"type": "integer"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/sources/:id/actions/initiateDownload\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the file from Repositories Gateway Source.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/sources/{id}/actions/initiateDownload\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/sources/{id}/content": {
"get": {
"tags": [
"files"
],
"summary": "Download a file from repositories gateway source",
"description": "Downloads the binary content of the specified file from its Repositories Gateway source.\\n\\n\n **Requires `download` permission on the file.**",
"responses": {
"200": {
"description": "Returns the binary file content as a downloadable stream."
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "Repositories Gateway file id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/sources/:id/content\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # Repositories Gateway file id\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/sources/{id}/content\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/content/link/{ref}": {
"get": {
"summary": "Download a file via a reference link",
"description": "### Description:\n Downloads the file identified by the provided reference link.\n### Precondition:\n Must be assigned the `download` permission for the file.\n### Response:\n The file content is streamed to the user.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "ref",
"required": true,
"description": "The unique reference for the download link.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The file download request by reference link was successful.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_DLP_LOCKED": {
"summary": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"description": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"value": {
"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."
}
]
}
},
"ERR_ENTITY_IS_SECURE_FOLDER": {
"summary": "Operation not permitted on restricted Folder.",
"description": "Operation not permitted on restricted Folder.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/actions/content/link/:ref\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nref = \"VALUE\" # The unique reference for the download link.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/actions/content/link/{ref}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/preview/file/{id}": {
"get": {
"summary": "Preview a file",
"description": "### Description:\n Returns the preview content for the specified file via the Repositories Gateway.\n### Precondition:\n User must have the `view` permission for the file.\n### Response:\n The preview content is returned.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier of the entity.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "The preview content has been successfully returned."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS": {
"summary": "Target user has insufficient access permissions",
"description": "Target user has insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"message": "Target user has insufficient access permissions"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/preview/file/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/preview/file/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/members": {
"post": {
"summary": "Share files",
"description": "### Description:\n Shares specified files with multiple users.\n### Precondition:\n Must be assigned the `user_add` permission for the folder.\n### Response:\n Shares the files with the specified users.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "updateIfExists",
"required": false,
"description": "If set to `true`, updates the member if they already exist and have a different folder role.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "If set to `true`, the operation will continue for the valid items even if some items result in failure.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "downgradeNested",
"required": false,
"description": "If set to `true`, demote the user member role in all applicable nested folders.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileMembersPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "All files were successfully shared with the specified users.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FolderFileAddMembers"
}
}
}
},
"207": {
"description": "Files were partially shared — some users were added successfully while others failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FolderFileAddMembers"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_IS_BASE_DIR": {
"summary": "Operation not permitted on Base Folder",
"description": "Operation not permitted on Base Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
},
"ERR_ENTITY_IS_MY_DIR": {
"summary": "Operation not permitted on Tray Folder",
"description": "Operation not permitted on Tray Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
},
"ERR_ENTITY_IS_SYNC_DIR": {
"summary": "Operation not permitted on My Folder",
"description": "Operation not permitted on My Folder",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SYNC_DIR",
"message": "Operation not permitted on My Folder"
}
]
}
},
"ERR_ENTITY_IS_SECURE_FOLDER": {
"summary": "Operation not permitted on restricted Folder.",
"description": "Operation not permitted on restricted Folder.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
},
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_LICENSE_MAX_USERS_COUNT_REACHED": {
"summary": "License count has been reached",
"description": "License count has been reached",
"value": {
"errors": [
{
"code": "ERR_LICENSE_MAX_USERS_COUNT_REACHED",
"message": "License count has been reached"
}
]
}
},
"ERR_USER_HAS_NO_USER_TYPE": {
"summary": "User has no profile",
"description": "User has no profile",
"value": {
"errors": [
{
"code": "ERR_USER_HAS_NO_USER_TYPE",
"message": "User has no profile"
}
]
}
},
"ERR_USER_TYPE_NO_ACCESS": {
"summary": "Permission denied",
"description": "Permission denied",
"value": {
"errors": [
{
"code": "ERR_USER_TYPE_NO_ACCESS",
"message": "Permission denied"
}
]
}
},
"ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST": {
"summary": "Distribution list user is not allowed to register",
"description": "Distribution list user is not allowed to register",
"value": {
"errors": [
{
"code": "ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST",
"message": "Distribution list user is not allowed to register"
}
]
}
},
"ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS": {
"summary": "Target user has insufficient access permissions",
"description": "Target user has insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
"message": "Target user has insufficient access permissions"
}
]
}
},
"ERR_PROFILE_COLLABORATION_DISABLED": {
"summary": "User's profile has no collaboration access",
"description": "User's profile has no collaboration access",
"value": {
"errors": [
{
"code": "ERR_PROFILE_COLLABORATION_DISABLED",
"message": "User's profile has no collaboration access"
}
]
}
},
"ERR_ENTITY_IS_OWNER": {
"summary": "Operation not permitted on owner member",
"description": "Operation not permitted on owner member",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_OWNER",
"message": "Operation not permitted on owner member"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_CLIENT_OBJECT": {
"summary": "Operation is not allowed on this client object",
"description": "Operation is not allowed on this client object",
"value": {
"errors": [
{
"code": "ERR_CLIENT_OBJECT",
"message": "Operation is not allowed on this client object"
}
]
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_ENTITY_EXISTS, ERR_ENTITY_ROLE_IS_ASSIGNED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_EXISTS": {
"summary": "Entity exists",
"description": "Entity exists",
"value": {
"errors": [
{
"code": "ERR_ENTITY_EXISTS",
"message": "Entity exists"
}
]
}
},
"ERR_ENTITY_ROLE_IS_ASSIGNED": {
"summary": "Cannot assign already assigned role",
"description": "Cannot assign already assigned role",
"value": {
"errors": [
{
"code": "ERR_ENTITY_ROLE_IS_ASSIGNED",
"message": "Cannot assign already assigned role"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/members\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"notify\": true,\n \"emails\": [\n \"string\"\n ],\n \"userIds\": [\n \"string\"\n ],\n \"ids\": [\n \"string\"\n ],\n \"roleId\": 1,\n \"message\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/members\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"notify\": true,\n \"emails\": [\n \"string\"\n],\n \"userIds\": [\n \"string\"\n],\n \"ids\": [\n \"string\"\n],\n \"roleId\": 1,\n \"message\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/shared": {
"get": {
"summary": "Get shared files",
"description": "### Description:\n 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.\n### Precondition:\n If the user is assigned the Restricted profile, the \"Collaboration Allowed\" setting must be turned on to get results.\n### Response:\n Returns the list of files that have been shared with the user.\n### Sorting:\n Sorting can be applied using two query parameters: `orderBy` for the field name,\n and `orderType` for the sort order, which can be either `asc` or `desc`.\n### Sorting field options:\n | FIELD_NAME | Description |\n |------------|-------------|\n | name | The name of the file |\n | size | The size of the file |\n | shared | The datetime when the file was shared |\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "orderBy",
"required": false,
"description": "Field to sort by. Default is `shared`.
Allowed values: `name`, `size`, `shared`, `sharedBy`, `modified`.",
"schema": {
"type": "string",
"enum": [
"name",
"size",
"shared",
"sharedBy",
"modified"
]
}
},
{
"in": "query",
"name": "orderType",
"required": false,
"description": "Sort direction. `asc` for ascending, `desc` for descending. Default is `desc`.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
{
"in": "query",
"name": "limit",
"required": false,
"description": "Range limit.",
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"in": "query",
"name": "offset",
"required": false,
"description": "Range offset.",
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
}
],
"responses": {
"200": {
"description": "Successfully returned the list of files shared with the user.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/shared\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/shared\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/members/me": {
"delete": {
"summary": "Remove access to shared file",
"description": "### Description:\n Removes the current user's access to the specified file that was shared with them.\n### Precondition:\n The file must have been shared with the user.\n### Response:\n Removes the user's access to the shared file.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "The user has been successfully removed from the file."
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/files/:id/members/me\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/files/{id}/members/me\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/previewSupport": {
"get": {
"summary": "Get file preview status",
"description": "### Description:\n Gets the status of the specified file to determine if the file type is supported for preview.\n### Precondition:\n Must be assigned the `view` permission for the folder.\n### Response:\n Returns confirmation as to whether the file type is supported for preview.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "id:in",
"required": true,
"explode": true,
"style": "form",
"description": "Comma-separated list of file UUIDs to check for preview support.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Returns a list of unique identifiers (UUIDs) of the files supported for preview.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FilePreviewSupport"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/files/previewSupport?id:in=VALUE\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/previewSupport\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nparams = {\n \"id:in\": \"VALUE\",\n}\nresponse = requests.get(url, params=params, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/files/actions/downloadLink": {
"post": {
"summary": "Get link for downloading files and folders",
"description": "### Description:\n Generates a link for downloading specified folders and files.\n### Precondition:\n Must be assigned the download permission for the specified files and folders.\n### Response:\n A download link is generated and returned.\n 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.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "partialSuccess",
"required": false,
"description": "Indicates whether the operation should proceed if some files/folders fail the check.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "extensions",
"required": false,
"explode": true,
"style": "form",
"description": "Filter results to include only files with the specified comma-separated list of extensions.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PostFileZipStatusBodyRequest"
}
}
}
},
"responses": {
"200": {
"description": "The download link has been successfully generated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DownloadLink"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/actions/downloadLink\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fileIds\": [\n \"string\"\n ],\n \"folderIds\": [\n \"string\"\n ],\n \"fileId\": \"string\",\n \"versionId\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/files/actions/downloadLink\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"fileIds\": [\n \"string\"\n],\n \"folderIds\": [\n \"string\"\n],\n \"fileId\": \"string\",\n \"versionId\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/admin/files": {
"put": {
"summary": "Update files",
"description": "### Description:\n Updates the metadata of multiple files at the same time.\n### Precondition:\n Must be an administrator with access to the Files and Folders page in the Kiteworks PDN Admin.\n### Response:\n Updates the selected files.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminFilePutRequest"
}
}
}
},
"responses": {
"200": {
"description": "The files have been successfully updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Files"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "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",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_ENTITY_DELETED": {
"summary": "Entity is deleted",
"description": "Entity is deleted",
"value": {
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
},
"ERR_ENTITY_DLP_LOCKED": {
"summary": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"description": "One or more files have been quarantined and are not available to download. Please contact your administrator for assistance.",
"value": {
"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."
}
]
}
},
"ERR_ENTITY_IS_ATTACHMENT": {
"summary": "Operation not permitted on attachment",
"description": "Operation not permitted on attachment",
"value": {
"errors": [
{
"code": "ERR_ENTITY_IS_ATTACHMENT",
"message": "Operation not permitted on attachment"
}
]
}
},
"ERR_ENTITY_NOT_SCANNED": {
"summary": "One or more files are undergoing security and privacy scans. Please try again later.",
"description": "One or more files are undergoing security and privacy scans. Please try again later.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_NOT_SCANNED",
"message": "One or more files are undergoing security and privacy scans. Please try again later."
}
]
}
},
"ERR_ENTITY_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_EXCEEDS_MAX_VALUE, ERR_INPUT_PAST_DATE, ERR_INVALID_PARAMETER, ERR_SYSTEM_EXTEND_FILE_EXPIRATION_DISABLED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_EXCEEDS_MAX_VALUE": {
"summary": "Field value exceeds maximum allowed value",
"description": "Field value exceeds maximum allowed value",
"value": {
"errors": [
{
"code": "ERR_INPUT_EXCEEDS_MAX_VALUE",
"message": "Field value exceeds maximum allowed value"
}
]
}
},
"ERR_INPUT_PAST_DATE": {
"summary": "Field value should be future date",
"description": "Field value should be future date",
"value": {
"errors": [
{
"code": "ERR_INPUT_PAST_DATE",
"message": "Field value should be future date"
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_SYSTEM_EXTEND_FILE_EXPIRATION_DISABLED": {
"summary": "Extending file expiration is not allowed",
"description": "Extending file expiration is not allowed",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_EXTEND_FILE_EXPIRATION_DISABLED",
"message": "Extending file expiration is not allowed"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/admin/files\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"string\"\n ],\n \"expire\": \"2024-01-15\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/admin/files\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"ids\": [\n \"string\"\n],\n \"expire\": \"2024-01-15\"\n}\nresponse = requests.put(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/admin/files/{id}/actions/rescan": {
"post": {
"summary": "Scan a file for security",
"description": "### Description:\n Runs a security scan on the specified file.\n### Precondition:\n Must authenticate as an administrator with a role allowing for manually scanning files for security.\n### Response:\n 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.\n",
"tags": [
"files"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "returnEntity",
"required": false,
"description": "If true, includes the entity in the response body.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "with",
"required": false,
"description": "Specifies additional fields to include in the response.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "mode",
"required": false,
"description": "Determines the detail level of the response body.",
"schema": {
"type": "string",
"enum": [
"compact",
"full_no_links",
"full_with_links",
"full"
]
}
}
],
"responses": {
"201": {
"description": "The file has been successfully submitted for rescan.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminFileRescan"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_ADMIN",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_ADMIN": {
"summary": "Insufficient admin access permissions",
"description": "Insufficient admin access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_ADMIN",
"message": "Insufficient admin access permissions"
}
]
}
}
}
}
}
},
"404": {
"description": "Not Found
Possible error codes: ERR_ENTITY_FILE_IS_NOT_FOUND, ERR_ENABLED_SCANNING_SERVICE_IS_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ENTITY_FILE_IS_NOT_FOUND": {
"summary": "The file is not found",
"description": "The file is not found",
"value": {
"errors": [
{
"code": "ERR_ENTITY_FILE_IS_NOT_FOUND",
"message": "The file is not found"
}
]
}
},
"ERR_ENABLED_SCANNING_SERVICE_IS_NOT_FOUND": {
"summary": "No enabled scanning service is found",
"description": "No enabled scanning service is found",
"value": {
"errors": [
{
"code": "ERR_ENABLED_SCANNING_SERVICE_IS_NOT_FOUND",
"message": "No enabled scanning service is found"
}
]
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: ERR_SCANNING_IN_PROGRESS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_SCANNING_IN_PROGRESS": {
"summary": "Scanning in progress. Please rescan later.",
"description": "Scanning in progress. Please rescan later.",
"value": {
"errors": [
{
"code": "ERR_SCANNING_IN_PROGRESS",
"message": "Scanning in progress. Please rescan later."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/admin/files/:id/actions/rescan\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/admin/files/{id}/actions/rescan\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"Errors": {
"type": "object",
"properties": {
"error": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"FileCopyPostBodyRequest": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "List of file UUIDs to copy. Cannot be used together with `id:in` in the query string."
},
"destinationFolderId": {
"type": "string",
"description": "UUID of the destination folder to copy the files into."
},
"replace": {
"type": "boolean",
"description": "If true, overwrites existing files in the destination folder if they share the same name."
},
"newFileName": {
"type": "string",
"maxLength": 255,
"description": "New name for the copied file. Only applicable when copying a single file into the same folder to avoid a name conflict."
}
},
"required": [
"destinationFolderId"
]
},
"File": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) of the file."
},
"parentId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) of the parent folder."
},
"name": {
"type": "string",
"description": "Name of the object."
},
"type": {
"type": "string",
"description": "Type of the object.
`f` – File.
`d` – Folder."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) who created the file."
},
"creator": {
"description": "Details of the user who created the object.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"created": {
"type": "string",
"format": "date",
"description": "The date and time when the object was created."
},
"modified": {
"type": "string",
"format": "date",
"description": "The date and time when the object was last modified."
},
"expire": {
"type": "string",
"format": "date",
"description": "Expiration timestamp of the object, if applicable."
},
"permissions": {
"description": "List of permissions associated with the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the object has been deleted."
},
"permDeleted": {
"type": "boolean",
"description": "Indicates whether the object has been permanently deleted."
},
"permalink": {
"type": "string",
"description": "Permanent URL link to access the file."
},
"path": {
"type": "string",
"description": "Path to the object in the hierarchy."
},
"members": {
"description": "List of members who have access to the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
},
"vendorDocId": {
"type": "string",
"description": "Vendor document ID associated with the object."
},
"vendorDocName": {
"type": "string",
"description": "Name of the vendor document associated with the object."
},
"secure": {
"type": "boolean",
"description": "Indicates whether the folder or the parent folder containing the file is marked as secure."
},
"source": {
"type": "integer",
"description": "ID representing the source of the object (1 - Salesforce, 2 - Teams)."
},
"modifier": {
"description": "The user who last modified the file.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"size": {
"type": "integer",
"description": "The size of the file in bytes."
},
"mime": {
"type": "string",
"description": "The MIME type of the file."
},
"fingerprint": {
"type": "string",
"description": "A unique hash identifying the file."
},
"fingerprints": {
"type": "array",
"description": "List of fingerprints associated with the file.",
"items": {
"$ref": "#/components/schemas/Fingerprint"
}
},
"clientCreated": {
"type": "string",
"format": "date",
"description": "The date and time when the file was created on the client side."
},
"clientModified": {
"type": "string",
"format": "date",
"description": "The date and time when the file was last modified on the client side."
},
"overriddenExpire": {
"type": "boolean",
"description": "Indicates whether the expiration date for the file has been overridden."
},
"sharedBy": {
"description": "The user who shared the file.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"sharedTime": {
"type": "string",
"format": "date",
"description": "The date and time when the file was shared."
},
"parent": {
"description": "The parent folder of the file.",
"allOf": [
{
"$ref": "#/components/schemas/Folder"
}
]
},
"originalFileId": {
"type": "string",
"format": "uuid",
"description": "The ID of the original file if this one is a copy."
},
"avStatus": {
"type": "string",
"description": "Indicates the file version's availability status based on Antivirus (AV) settings and whether it has been scanned or detected as infected."
},
"dlpStatus": {
"type": "string",
"description": "Indicates the file version's availability status based on Data Loss Prevention (DLP) settings and whether it has been scanned or detected as infected."
},
"adminQuarantineStatus": {
"type": "string",
"description": "Indicates the file version's availability status based on the administrator's quarantine status."
},
"locked": {
"type": "boolean",
"description": "Indicates if the file is locked."
},
"lockUser": {
"description": "The user who locked the file.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"isShared": {
"type": "boolean",
"description": "Indicates if the file is shared with other users."
},
"lastModifiedBy": {
"description": "The user who last modified the file.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"pushedObject": {
"description": "Details about the pushed object, if any.",
"allOf": [
{
"$ref": "#/components/schemas/PushedObject"
}
]
},
"pathIds": {
"type": "string",
"format": "uuid",
"description": "A list of IDs representing the path of the file within the folder hierarchy."
},
"wopiapp": {
"description": "WOPI-related information for the file when used in a mobile app.",
"allOf": [
{
"$ref": "#/components/schemas/MobileInfo"
}
]
},
"pushed": {
"type": "boolean",
"description": "Indicates if the file has been pushed to a mobile app."
},
"tags": {
"description": "List of tags associated with the file.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
},
"safeEdit": {
"description": "Information regarding the file's SafeEdit settings.",
"allOf": [
{
"$ref": "#/components/schemas/SafeEdit"
}
]
},
"versionsCount": {
"type": "integer",
"description": "The total number of versions for the file."
},
"tracking_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Tracking identifier associated with the file upload."
}
}
},
"FileLockPostRequest": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "A list of file object IDs to be locked/unlocked."
}
}
},
"BulkOperationLockFile": {
"type": "object",
"properties": {
"errors": {
"description": "List of errors for files that could not be locked.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ErrorString"
}
},
"successIds": {
"type": "array",
"description": "List of IDs for successfully locked files.",
"items": {
"type": "string"
}
},
"data": {
"description": "List of file objects that were successfully locked.",
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
}
}
},
"FileMovePostBodyRequest": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "List of file UUIDs to move. Cannot be used together with `id:in` in the query string."
},
"destinationFolderId": {
"type": "string",
"description": "UUID of the destination folder to move the files into."
},
"replace": {
"type": "boolean",
"description": "If true, overwrites existing files in the destination folder if they share the same name."
}
},
"required": [
"destinationFolderId"
]
},
"MetaData": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of items available."
},
"limit": {
"type": "integer",
"description": "Maximum number of items returned per page."
},
"offset": {
"type": "integer",
"description": "Number of items skipped before the current page."
}
}
},
"FileUpdateRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "The new name for the file."
},
"expire": {
"type": "string",
"format": "date",
"description": "The updated expiration date for the file."
},
"replace": {
"type": "boolean",
"description": "Indicates whether to replace the existing file if one with the same name already exists."
}
}
},
"SourceFile": {
"required": [
"id",
"name",
"parentId",
"type",
"wopiapp"
],
"properties": {
"id": {
"description": "Unique SourceContent identifier",
"type": "string"
},
"name": {
"description": "Display name of the source content item",
"type": "string"
},
"parentId": {
"description": "Parent source content unique identifier",
"type": "string"
},
"type": {
"description": "Source content type. Accepted values: \\`d\\` (folder), \\`f\\` (file)",
"type": "string"
},
"created": {
"description": "Creation timestamp of the source content in UTC",
"type": "string",
"format": "date"
},
"modified": {
"description": "Last modification timestamp of the source content in UTC",
"type": "string",
"format": "date"
},
"status": {
"description": "Current availability status of the source content item",
"type": "string"
},
"deleted": {
"description": "Indicates whether the source content is deleted",
"type": "boolean"
},
"path": {
"description": "Full path of the source content",
"type": "string"
},
"userRoleId": {
"description": "Current user role id (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "integer"
},
"creator": {
"description": "File's creator (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/UserBasicInfo"
},
"permissions": {
"description": "Current user's permissions (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"wopiapp": {
"description": "WOPI info for iOS app",
"type": "boolean"
},
"rootId": {
"description": "Unique identifier of the root-level source content ancestor (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"pathIds": {
"description": "Ordered list of ancestor identifiers representing the full path from root to this source content item (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"sourceTypeId": {
"description": "Unique identifier of the ECM source type this content belongs to (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"totalFilesCount": {
"description": "Total number of files in the source content (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"totalFoldersCount": {
"description": "Total number of folders in the source content (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"parent": {
"description": "Parent source content item (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/SourceContent"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
},
"locked": {
"description": "Indicates whether the file is locked",
"type": "boolean"
},
"size": {
"description": "Size of the source file in bytes",
"type": "integer"
},
"fingerprint": {
"description": "File content fingerprint",
"type": "string"
},
"expire": {
"description": "Date and time after which the source file expires and becomes unavailable",
"type": "string"
},
"mime": {
"description": "File MIME type",
"type": "string"
},
"avStatus": {
"description": "Check file availability status according to AV settings and file scanned/infected status",
"type": "string"
},
"dlpStatus": {
"description": "Check file availability status according to DLP settings and file scanned/infected status",
"type": "string"
},
"lockedUserName": {
"description": "Username/email of user who locked the file",
"type": "string"
},
"lockUser": {
"description": "User who locked the file",
"$ref": "#/components/schemas/UserBasicInfo"
}
}
},
"RefreshToken": {
"description": "Class RefreshToken",
"required": [
"refreshToken",
"scope"
],
"properties": {
"userId": {
"description": "Unique identifier of the user to whom the refresh token belongs",
"type": "integer"
},
"expire": {
"description": "Date and time after which the refresh token is no longer valid",
"type": "string",
"format": "date-time"
},
"scope": {
"description": "OAuth scope of the refresh token",
"type": "string"
},
"refreshToken": {
"description": "Refresh token value",
"type": "string"
}
}
},
"Members": {
"type": "object",
"properties": {
"data": {
"description": "List of members with access to the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
},
"metadata": {
"description": "Pagination metadata for the result set.",
"allOf": [
{
"$ref": "#/components/schemas/MetaData"
}
]
}
}
},
"MemberGroup": {
"description": "Class MemberGroup",
"required": [
"groupId",
"objectId",
"roleId"
],
"properties": {
"objectId": {
"description": "Unique identifier of the folder this member belongs to",
"type": "string"
},
"roleId": {
"description": "Unique identifier of the role assigned to this member",
"type": "integer"
},
"group": {
"description": "Details of the LDAP group that is a member (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/LdapGroup"
},
"role": {
"description": "Details of the role assigned to this member (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/Role"
},
"inheritRoleId": {
"description": "Unique identifier of the role inherited from the parent folder (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "integer"
},
"allowedFolderRoleId": {
"description": "List of role identifiers that are permitted for this folder membership (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "array",
"items": {
"type": "string"
}
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
},
"groupId": {
"description": "Unique identifier of the LDAP group assigned as a member",
"type": "integer"
},
"user": {
"description": "Details of the user who is a member (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/User"
}
}
},
"Member": {
"type": "object",
"properties": {
"objectId": {
"type": "string",
"description": "Unique identifier (UUID) of the associated object (file or folder)."
},
"roleId": {
"type": "integer",
"description": "Role assigned to the member."
},
"userId": {
"type": "string",
"description": "Unique identifier (UUID) of the user."
},
"groupId": {
"type": "integer",
"description": "Unique identifier of the LDAP group."
},
"user": {
"description": "User details of the member.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"role": {
"description": "Role details assigned to the member.",
"allOf": [
{
"$ref": "#/components/schemas/Role"
}
]
},
"group": {
"description": "Group details if the member belongs to a group.",
"allOf": [
{
"$ref": "#/components/schemas/Group"
}
]
},
"sharedBy": {
"description": "Details of the user who shared the file or folder.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"created": {
"type": "string",
"format": "date",
"description": "Date when the file or folder was shared."
},
"inheritRoleId": {
"type": "integer",
"description": "Inherited role ID from the parent folder, if applicable."
},
"allowedFolderRoleId": {
"type": "array",
"description": "List of allowed folder role IDs.",
"items": {
"type": "integer"
}
},
"email": {
"type": "string",
"description": "Email associated with the member."
},
"rank": {
"type": "integer",
"description": "Rank of the member role."
},
"originFolder": {
"readOnly": true
}
}
},
"FilePathResponse": {
"description": "Represents the full ancestor path of a file, from the workspace root down to the file's parent folder. Returned by the GET /files/{id}/path endpoint.",
"properties": {
"data": {
"description": "Ordered list of folder nodes representing the path from the workspace root to the file's parent folder.",
"type": "array",
"items": {
"$ref": "FolderTreeItem"
}
},
"links": {
"description": "Optional HATEOAS links. Present only when the request includes link options.",
"type": "array",
"items": {
"$ref": "HateoasLink"
}
}
}
},
"Task": {
"description": "Class Task",
"required": [
"assigneeId",
"created",
"due",
"id",
"status",
"userId"
],
"properties": {
"id": {
"description": "Task unique identifier",
"type": "integer"
},
"assigneeId": {
"description": "Assigned User unique identifier",
"type": "string"
},
"assignee": {
"description": "User assigned to complete the task (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/User"
},
"due": {
"description": "Date and time by which the task must be completed",
"type": "string",
"format": "date"
},
"parentId": {
"description": "Parent Comment identifier",
"type": "integer"
},
"objectId": {
"description": "Object identifier Task belongs to",
"type": "string"
},
"userId": {
"description": "Identifier of User who created a Task",
"type": "string"
},
"user": {
"description": "User who created the task (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/User"
},
"created": {
"description": "Date and time the task was created",
"type": "string",
"format": "date"
},
"modified": {
"description": "Date and time the task was last modified",
"type": "string",
"format": "date"
},
"contents": {
"description": "Body text of the task",
"type": "string"
},
"deleted": {
"description": "Indicates whether the task is deleted",
"type": "boolean"
},
"folderId": {
"description": "Identifier of Object's parent Folder",
"type": "string"
},
"status": {
"description": "Task status. Accepted values: `D` (Defined), `P` (In Progress), `C` (Completed)",
"type": "string"
},
"file": {
"description": "File the task is tied to (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/File"
},
"permissions": {
"description": "Current user's permissions (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Task.Post": {
"description": "Class Task",
"required": [
"assigneeId",
"due",
"contents"
],
"properties": {
"assigneeId": {
"description": "Assignee user unique identifier",
"type": "integer"
},
"due": {
"description": "Date and time by which the task must be completed",
"type": "string",
"format": "date"
},
"parentId": {
"description": "Parent Comment identifier",
"type": "integer"
},
"contents": {
"description": "Body text of the task",
"type": "string"
},
"addLinks": {
"description": "Indicates whether HATEOAS links should be included in the response",
"type": "boolean"
}
}
},
"Version": {
"description": "Class Version",
"required": [
"id",
"name",
"objectId",
"userId",
"versionNumber"
],
"properties": {
"id": {
"description": "The unique identifier of the file version.",
"type": "string"
},
"versionNumber": {
"description": "The version number of the file.",
"type": "integer"
},
"deleted": {
"description": "Indicates whether this version of the file has been deleted.",
"type": "boolean"
},
"created": {
"description": "The creation date of this file version.",
"type": "string",
"format": "date"
},
"userId": {
"description": "The unique identifier of the user who created this file version.",
"type": "string"
},
"size": {
"description": "The size of the file content in bytes.",
"type": "integer"
},
"fingerprint": {
"description": "A unique hash identifying the file.",
"type": "string"
},
"fingerprintAlgo": {
"description": "The algorithm used to generate the fingerprint (e.g., sha3-256, md5).",
"type": "string"
},
"backend": {
"description": "The backend system associated with the file version.",
"type": "string"
},
"mime": {
"description": "The MIME type of the file version.",
"type": "string"
},
"name": {
"description": "The name of the file version.",
"type": "string"
},
"creator": {
"description": "The user who created the file version. (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/UserBasicInfo"
},
"objectId": {
"description": "The object ID (UUID) for the file version.",
"type": "string"
},
"clientCreated": {
"description": "The date and time the file version was created on the client side.",
"type": "string",
"format": "date"
},
"clientModified": {
"description": "The date and time the file version was last modified on the client side.",
"type": "string",
"format": "date"
},
"avStatus": {
"description": "Indicates the file version's availability status based on Antivirus (AV) settings and whether it has been scanned or detected as infected.",
"type": "string"
},
"dlpStatus": {
"description": "Indicates the file version's availability status based on Data Loss Prevention (DLP) settings and whether it has been scanned or detected as infected.",
"type": "string"
},
"adminQuarantineStatus": {
"description": "Indicates the file version\\'s availability status based on the administrator\\'s quarantine status. ",
"type": "string"
},
"storageAvailable": {
"description": "Indicates whether the file is accessible on any storage volume.",
"type": "boolean"
},
"fingerprints": {
"description": "A list of fingerprints associated with the file version.",
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"description": "List of tags associated with the file.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Preview": {
"description": "Class Preview",
"properties": {
"link": {
"description": "Preview link for the file",
"type": "string"
},
"pdf": {
"description": "PDF file for the preview",
"type": "string"
},
"viewUrl": {
"description": "URL for viewing the preview",
"type": "string"
},
"status": {
"description": "Preview processing status. Accepted values: `processing`, `preview`, `failed`",
"type": "string"
},
"type": {
"description": "Format of the generated preview, such as image or PDF",
"type": "string"
},
"metadata": {
"description": "Additional metadata about the preview, such as dimensions or page count",
"type": "string"
},
"mime": {
"description": "MIME type of the preview file",
"type": "string"
},
"native": {
"description": "Indicates whether the preview is a native render",
"type": "boolean"
},
"watermark": {
"description": "Watermark applied to the preview",
"type": "string"
},
"tdfOriginalExtension": {
"description": "Original file extension for TDF files",
"type": "string"
}
}
},
"Content.Post": {
"description": "Class Content",
"required": [
"content",
"name"
],
"properties": {
"addLinks": {
"description": "Indicates whether HATEOAS links should be included in the response",
"type": "boolean"
},
"name": {
"description": "Display name of the file",
"type": "string"
},
"content": {
"description": "Raw content body of the file being created",
"type": "string"
},
"clientCreated": {
"description": "Date and time when the file was created on the client side",
"type": "integer"
},
"clientModified": {
"description": "Date and time when the file was last modified on the client side",
"type": "integer"
},
"note": {
"description": "Indicates whether the file should be uploaded as a note",
"type": "integer"
},
"disableAutoVersion": {
"description": "Indicates whether the file should be prevented from being saved as a new version",
"type": "boolean"
}
}
},
"FileNameRequest.Post": {
"properties": {
"fileType": {
"description": "The file type",
"type": "string"
},
"fileName": {
"description": "The file name",
"type": "string"
}
}
},
"Permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the permission."
},
"name": {
"type": "string",
"description": "Name of the permission."
},
"allowed": {
"type": "boolean",
"description": "Indicates whether the permission is granted (True) or denied (False)."
}
}
},
"FilePermissions": {
"description": "Class FilePermissions",
"properties": {
"fileId": {
"description": "Id of file",
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Comment": {
"description": "Class Comment",
"required": [
"contents",
"id",
"objectId",
"parentId",
"userId"
],
"properties": {
"id": {
"description": "Comment unique identifier",
"type": "integer"
},
"parentId": {
"description": "Unique identifier of the parent comment, if the comment is a reply",
"type": "integer"
},
"objectId": {
"description": "Unique identifier (UUID) of the file being commented on",
"type": "string"
},
"folderId": {
"description": "Unique identifier (UUID) of the folder containing the object being commented on",
"type": "string"
},
"userId": {
"description": "Unique identifier (UUID) of the user who authored the comment",
"type": "string"
},
"created": {
"description": "Date and time when the comment was created",
"type": "string",
"format": "date"
},
"modified": {
"description": "Date and time when the comment was last modified",
"type": "string",
"format": "date"
},
"contents": {
"description": "Text content of the comment",
"type": "string"
},
"deleted": {
"description": "Indicates whether the comment has been deleted",
"type": "boolean"
},
"isComment": {
"description": "Indicates whether the item is a comment",
"type": "boolean"
},
"object": {
"description": "File being commented on (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/BaseObject"
},
"author": {
"description": "Author of the comment (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/UserBasicInfo"
},
"parent": {
"description": "The comment this reply is responding to, if applicable (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/Comment"
},
"permissions": {
"description": "Permissions of the current user regarding the comment (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Comment.Post": {
"description": "Class Comment",
"required": [
"contents"
],
"properties": {
"parentId": {
"description": "Unique identifier of the parent comment. Set this value when replying to an existing comment",
"type": "integer"
},
"contents": {
"description": "Text content of the comment",
"type": "string"
},
"addLinks": {
"description": "Indicates whether HATEOAS links should be included in the response",
"type": "boolean"
}
}
},
"KPTransferStatus": {
"description": "Class KPTransferStatus",
"required": [
"errCode",
"fileHandle",
"id",
"kPObjectId",
"transactionId",
"userId"
],
"properties": {
"id": {
"description": "KP transfer status unique identifier",
"type": "string"
},
"transactionId": {
"description": "Unique transaction identifier for tracking the Repositories Gateway file transfer",
"type": "string"
},
"kPObjectId": {
"description": "Unique identifier of the Repositories Gateway object being transferred",
"type": "string"
},
"fileHandle": {
"description": "File handle used to reference the temporary file during the transfer process",
"type": "string"
},
"userId": {
"description": "The unique identifier of the user.",
"type": "string"
},
"errCode": {
"description": "Numeric error code returned when the file transfer fails",
"type": "string"
},
"status": {
"description": "Current status of the Repositories Gateway file transfer. Accepted values: `0` (received request), `1` (in progress), `2` (completed successfully), `99` (transfer failed)",
"type": "string"
},
"avStatus": {
"description": "AV scan status. Accepted values: `allowed`, `disallowed`, `scanning`",
"type": "string"
},
"dlpStatus": {
"description": "DLP scan status. Accepted values: `allowed`, `disallowed`, `scanning`",
"type": "string"
}
}
},
"FileMembersPostRequest": {
"type": "object",
"properties": {
"notify": {
"type": "boolean",
"description": "If set to `true`, notifies the user being invited to the file via email."
},
"emails": {
"type": "array",
"description": "List of email addresses for new members.",
"items": {
"type": "string",
"format": "email"
}
},
"userIds": {
"type": "array",
"description": "List of user IDs (UUID) for new members. (Recommended request size <= 100)",
"items": {
"type": "string"
}
},
"ids": {
"type": "array",
"description": "List of file UUIDs to share with the specified users.",
"items": {
"type": "string"
}
},
"roleId": {
"type": "integer",
"enum": [
8,
9
],
"description": "The role to assign to the new members.
`8` – Collaborator (can upload, edit, and download).
`9` – Viewer (read-only access)."
},
"message": {
"type": "string",
"description": "Optional message to include with the file sharing."
}
},
"required": [
"roleId"
]
},
"FolderFileAddMembers": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ErrorStringSchemaAccessVerifications"
}
},
"successIds": {
"type": "array",
"description": "List of succeeded IDs.",
"items": {
"type": "string"
}
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
}
}
},
"FilePreviewSupport": {
"type": "object",
"properties": {
"supportedIds": {
"type": "array",
"description": "Unique identifier (UUID) of the supported files",
"items": {
"type": "string"
}
}
}
},
"PostFileZipStatusBodyRequest": {
"type": "object",
"properties": {
"fileIds": {
"type": "array",
"maxItems": 1000,
"description": "List of file UUIDs to include in the bulk download. Maximum 1000 entries.",
"items": {
"type": "string"
}
},
"folderIds": {
"type": "array",
"maxItems": 100,
"description": "List of folder UUIDs to include in the bulk download. Maximum 100 entries.",
"items": {
"type": "string"
}
},
"fileId": {
"type": "string",
"description": "UUID of a single file to download. Use this for single-file downloads instead of `fileIds`."
},
"versionId": {
"type": "string",
"description": "The version ID of the specified file."
}
}
},
"DownloadLink": {
"type": "object",
"properties": {
"downloadLinks": {
"type": "array",
"description": "List of download URLs for the requested files.",
"items": {
"type": "string"
}
}
}
},
"AdminFilePutRequest": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"description": "List of file object IDs (UUID) to be updated.",
"items": {
"type": "string"
}
},
"expire": {
"type": "string",
"format": "date",
"description": "New expiration date for the selected files."
}
},
"required": [
"ids"
]
},
"Files": {
"type": "object",
"properties": {
"data": {
"description": "List of files.",
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
}
}
},
"AdminFileRescan": {
"type": "object",
"properties": {
"msg": {
"type": "string",
"description": "The successful response message"
}
}
},
"ErrorStringSchemaAccessVerifications": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
},
"field": {
"type": "string",
"description": "Associated field, if applicable."
},
"failedIds": {
"type": "array",
"description": "List of failed IDs.",
"items": {
"type": "string"
}
},
"accessVerification": {
"description": "Access Verification details",
"allOf": [
{
"$ref": "#/components/schemas/AccessVerificationApproval"
}
]
},
"referenceId": {
"type": "string",
"description": "Reference ID for the error"
}
}
},
"AccessVerificationApproval": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Access Verification ID"
},
"parentId": {
"type": "integer",
"description": "Unique identifier of the parent object."
},
"name": {
"type": "string",
"description": "Name of the object."
},
"type": {
"type": "string",
"description": "Type of the object.
`f` – File.
`d` – Folder."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) who created the object."
},
"creator": {
"description": "Details of the user who created the object.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"created": {
"type": "string",
"format": "date",
"description": "The date and time when the object was created."
},
"modified": {
"type": "string",
"format": "date",
"description": "The date and time when the object was last modified."
},
"expire": {
"type": "string",
"format": "date",
"description": "Expiration timestamp of the object, if applicable."
},
"permissions": {
"description": "List of permissions associated with the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the object has been deleted."
},
"permDeleted": {
"type": "boolean",
"description": "Indicates whether the object has been permanently deleted."
},
"permalink": {
"type": "string",
"description": "Permanent URL link to access the object."
},
"path": {
"type": "string",
"description": "Path to the object in the hierarchy."
},
"members": {
"description": "List of members who have access to the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
},
"vendorDocId": {
"type": "string",
"description": "Vendor document ID associated with the object."
},
"vendorDocName": {
"type": "string",
"description": "Name of the vendor document associated with the object."
},
"secure": {
"type": "boolean",
"description": "Indicates whether the folder or the parent folder containing the file is marked as secure."
},
"source": {
"type": "integer",
"description": "ID representing the source of the object (1 - Salesforce, 2 - Teams)."
},
"requirements": {
"type": "array",
"description": "List of requirements for access verification",
"items": {
"$ref": "#/components/schemas/Requirement"
}
}
}
},
"UserBasic": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier (UUID) for the user."
},
"email": {
"type": "string",
"description": "Email address associated with the user."
},
"name": {
"type": "string",
"description": "Full name of the user."
},
"profileIcon": {
"type": "string",
"description": "URL or identifier for the user's profile icon."
}
}
},
"Requirement": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Requirement ID"
},
"parentId": {
"type": "integer",
"description": "Unique identifier of the parent object."
},
"name": {
"type": "string",
"description": "Name of the object."
},
"type": {
"type": "string",
"description": "Type of the object.
`f` – File.
`d` – Folder."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) who created the object."
},
"creator": {
"description": "Details of the user who created the object.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"created": {
"type": "string",
"format": "date",
"description": "The date and time when the object was created."
},
"modified": {
"type": "string",
"format": "date",
"description": "The date and time when the object was last modified."
},
"expire": {
"type": "string",
"format": "date",
"description": "Expiration timestamp of the object, if applicable."
},
"permissions": {
"description": "List of permissions associated with the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the object has been deleted."
},
"permDeleted": {
"type": "boolean",
"description": "Indicates whether the object has been permanently deleted."
},
"permalink": {
"type": "string",
"description": "Permanent URL link to access the object."
},
"path": {
"type": "string",
"description": "Path to the object in the hierarchy."
},
"members": {
"description": "List of members who have access to the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
},
"vendorDocId": {
"type": "string",
"description": "Vendor document ID associated with the object."
},
"vendorDocName": {
"type": "string",
"description": "Name of the vendor document associated with the object."
},
"secure": {
"type": "boolean",
"description": "Indicates whether the folder or the parent folder containing the file is marked as secure."
},
"source": {
"type": "integer",
"description": "ID representing the source of the object (1 - Salesforce, 2 - Teams)."
},
"approvers": {
"description": "List of approvers for the requirement"
},
"asset_class": {
"description": "Asset class associated with the requirement",
"allOf": [
{
"$ref": "#/components/schemas/RiskPolicy"
}
]
},
"matched_recipients": {
"type": "array",
"description": "List of succeeded recipient emails.",
"items": {
"type": "string"
}
}
}
},
"RiskPolicy": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Risk Policy ID"
},
"parentId": {
"type": "integer",
"description": "Unique identifier of the parent object."
},
"name": {
"type": "string",
"description": "Risk Policy Name"
},
"type": {
"type": "string",
"description": "Type of the object.
`f` – File.
`d` – Folder."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) who created the object."
},
"creator": {
"description": "Details of the user who created the object.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"created": {
"type": "string",
"format": "date",
"description": "The date and time when the object was created."
},
"modified": {
"type": "string",
"format": "date",
"description": "The date and time when the object was last modified."
},
"expire": {
"type": "string",
"format": "date",
"description": "Expiration timestamp of the object, if applicable."
},
"permissions": {
"description": "List of permissions associated with the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the object has been deleted."
},
"permDeleted": {
"type": "boolean",
"description": "Indicates whether the object has been permanently deleted."
},
"permalink": {
"type": "string",
"description": "Permanent URL link to access the object."
},
"path": {
"type": "string",
"description": "Path to the object in the hierarchy."
},
"members": {
"description": "List of members who have access to the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
},
"vendorDocId": {
"type": "string",
"description": "Vendor document ID associated with the object."
},
"vendorDocName": {
"type": "string",
"description": "Name of the vendor document associated with the object."
},
"secure": {
"type": "boolean",
"description": "Indicates whether the folder or the parent folder containing the file is marked as secure."
},
"source": {
"type": "integer",
"description": "ID representing the source of the object (1 - Salesforce, 2 - Teams)."
},
"message": {
"type": "string",
"description": "Risk Policy Message"
}
}
},
"BaseObject": {
"description": "Class Object",
"required": [
"id",
"name",
"parentId",
"userId"
],
"properties": {
"id": {
"description": "Unique identifier of object",
"type": "string"
},
"created": {
"description": "Date and time when the object was created",
"type": "string",
"format": "date-time"
},
"deleted": {
"description": "Indicates whether the object is deleted",
"type": "boolean"
},
"permDeleted": {
"description": "Indicates whether the object is permanently deleted",
"type": "boolean"
},
"expire": {
"description": "Date and time when the object expires and becomes inaccessible",
"type": "string",
"format": "date-time"
},
"modified": {
"description": "Date and time when the object was last modified",
"type": "string",
"format": "date-time"
},
"name": {
"description": "Display name of the object",
"type": "string"
},
"parentId": {
"description": "Parent Folder identifier",
"type": "string"
},
"userId": {
"description": "Unique identifier of Object creator",
"type": "string"
},
"parent": {
"description": "Folder that directly contains this object (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/Folder"
},
"permalink": {
"description": "Permanent URL for accessing the object in the web application",
"type": "string"
},
"creator": {
"description": "Basic profile information of the user who created the object (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/UserBasicInfo"
},
"permissions": {
"description": "Current user's permissions (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"vendorDocId": {
"description": "Identifier of the corresponding document in the external vendor system (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"vendorDocName": {
"description": "Display name of the corresponding document in the external vendor system (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"source": {
"description": "Numeric code identifying the external system that originated this object (e.g. Salesforce, Teams)",
"type": "integer"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"UserBasicInfo": {
"required": [
"email",
"id",
"name"
],
"properties": {
"id": {
"description": "The unique identifier of the user",
"type": "string"
},
"name": {
"description": "The name of the user",
"type": "string"
},
"email": {
"description": "The user's email",
"type": "string"
},
"profileIcon": {
"description": "URL to the user's profile icon image",
"type": "string"
}
}
},
"Folder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) of the folder."
},
"parentId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) of the parent object."
},
"name": {
"type": "string",
"description": "Name of the object."
},
"type": {
"type": "string",
"description": "Type of the object.
`f` – File.
`d` – Folder."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) who created the folder."
},
"creator": {
"description": "Details of the user who created the object.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
},
"created": {
"type": "string",
"format": "date",
"description": "The date and time when the object was created."
},
"modified": {
"type": "string",
"format": "date",
"description": "The date and time when the object was last modified."
},
"expire": {
"type": "string",
"format": "date",
"description": "Expiration timestamp of the object, if applicable."
},
"permissions": {
"description": "List of permissions associated with the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"deleted": {
"type": "boolean",
"description": "Indicates whether the object has been deleted."
},
"permDeleted": {
"type": "boolean",
"description": "Indicates whether the object has been permanently deleted."
},
"permalink": {
"type": "string",
"description": "Permanent URL link to access the object."
},
"path": {
"type": "string",
"description": "Path to the folder in the hierarchy."
},
"members": {
"description": "List of members who have access to the object.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
},
"vendorDocId": {
"type": "string",
"description": "Vendor document ID associated with the object."
},
"vendorDocName": {
"type": "string",
"description": "Name of the vendor document associated with the object."
},
"secure": {
"type": "boolean",
"description": "Indicates whether the folder or the parent folder containing the file is marked as secure."
},
"source": {
"type": "integer",
"description": "ID representing the source of the object (1 - Salesforce, 2 - Teams)."
},
"isShared": {
"type": "boolean",
"description": "Indicates if the folder is shared with other users."
},
"syncable": {
"type": "boolean",
"description": "Indicates if the folder can be synced by Desktop Sync Client."
},
"fileLifetime": {
"type": "integer",
"description": "Time duration (in days) for which the files in this folder are kept after being added to the folder."
},
"description": {
"type": "string",
"description": "The description of the folder."
},
"isFavorite": {
"type": "boolean",
"description": "Indicates if the folder is marked as a favorite by the user."
},
"pushedFilesCount": {
"type": "integer",
"description": "The number of files that have been pushed to mobile apps in this folder."
},
"currentUserRole": {
"description": "The role of the current user in this folder.",
"allOf": [
{
"$ref": "#/components/schemas/Role"
}
]
},
"avStatus": {
"type": "string",
"description": "The Antivirus (AV) status of the folder."
},
"dlpStatus": {
"type": "string",
"description": "The Data Loss Prevention (DLP) status of the folder."
},
"totalMembersCount": {
"type": "integer",
"description": "Total number of members who have access to this folder."
},
"totalFoldersCount": {
"type": "integer",
"description": "Total number of subfolders within this folder."
},
"totalFilesCount": {
"type": "integer",
"description": "Total number of files within this folder."
},
"maxFolderExpiration": {
"type": "string",
"format": "date",
"description": "The maximum expiration date allowed for files in this folder."
},
"maxFileLifetime": {
"type": "integer",
"description": "The maximum duration (in days) that files in this folder can be kept after being added to the folder."
},
"isLdapGroupMember": {
"type": "boolean",
"description": "Indicates if the folder is part of an LDAP group."
},
"isUnderMyFolder": {
"type": "boolean",
"description": "Indicates if this folder is a subfolder of the user's \"My Folder\"."
},
"pathIds": {
"type": "string",
"description": "A list of IDs representing the path of the folder within the folder hierarchy."
},
"isRoot": {
"type": "boolean",
"description": "Indicates if this folder is a root folder."
},
"rootId": {
"type": "string",
"format": "uuid",
"description": "The ID of the root folder if this is a subfolder."
},
"useFolderQuota": {
"type": "boolean",
"description": "Indicates if a folder quota is applied to this folder."
},
"quota": {
"type": "integer",
"description": "The storage quota for the folder (in bytes)."
},
"size": {
"type": "integer",
"description": "The total storage size used by the folder (in bytes)."
},
"freeSpace": {
"type": "integer",
"description": "The amount of free space available in the folder (in bytes)."
},
"inheritanceEnabled": {
"type": "boolean",
"description": "Indicates if a folder inherits permissions from the parent folder"
}
}
},
"Role": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Role ID"
},
"name": {
"type": "string",
"description": "Role name"
},
"rank": {
"type": "integer",
"description": "Role rank"
},
"type": {
"type": "string",
"description": "Role type"
}
}
},
"Tag": {
"type": "object",
"properties": {
"guid": {
"type": "string",
"format": "uuid",
"description": "Unique identifier (UUID) for the tag."
},
"name": {
"type": "string",
"description": "Display name of the tag."
},
"type": {
"type": "string",
"description": "Type category of the tag."
}
}
},
"User": {
"description": "Class User",
"required": [
"basedirId",
"email",
"id",
"mydirId",
"name",
"syncdirId"
],
"properties": {
"id": {
"description": "The unique identifier of the user",
"type": "string"
},
"basedirId": {
"description": "The unique identifier of the user's root Kiteworks directory.",
"type": "string"
},
"created": {
"description": "Date and time the user account was created",
"type": "string",
"format": "date"
},
"email": {
"description": "The user's email",
"type": "string"
},
"mydirId": {
"description": "The unique identifier of the user's mydir system directory.",
"type": "string"
},
"name": {
"description": "The name of the user",
"type": "string"
},
"syncdirId": {
"description": "The unique identifier of the user's 'My Folder'.",
"type": "string"
},
"userTypeId": {
"description": "The unique identifier of the user type (profile).",
"type": "integer"
},
"internal": {
"description": "Indicates whether the user is an internal user",
"type": "boolean"
},
"profileIcon": {
"description": "URL to the user's profile icon image",
"type": "string"
},
"extDL": {
"description": "Indicates whether the user is an External Distribution List",
"type": "boolean"
},
"metadata": {
"description": "List of user's metadata",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserMetadata"
}
},
"adminRoleId": {
"description": "The ID of the admin role assigned to the user.",
"type": "integer"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"description": "Indicates whether the user is an actual kitework user",
"type": "boolean"
},
"suspended": {
"description": "Indicates whether the user is suspended",
"type": "boolean"
},
"deleted": {
"description": "Indicates whether the user has been deleted",
"type": "boolean"
},
"flags": {
"description": "Authentication type.\n * 0: No authentication,\n * 1: Authentication by kiteworks,\n * 2: Authentication by LDAP,\n * 4: Authentication by SSO",
"type": "integer"
},
"verified": {
"description": "Indicates whether the user is verified",
"type": "boolean"
},
"deactivated": {
"description": "Indicates whether the user has been deactivated",
"type": "boolean"
},
"lastActivityDateTime": {
"description": "User's last activity datetime",
"type": "string",
"format": "date"
},
"passwordExpirationDateTime": {
"description": "The exact timestamp when the user's password will expire",
"type": "string",
"format": "date"
}
}
},
"UserMetadata": {
"description": "Class UserMetadata",
"properties": {
"name": {
"description": "Key name of the custom metadata attribute associated with the user",
"type": "string"
},
"value": {
"description": "Value assigned to the custom metadata attribute for the user",
"type": "string"
}
}
},
"Group": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "LDAP Group ID"
},
"name": {
"type": "string",
"description": "LDAP Group name"
},
"dn": {
"type": "string",
"description": "LDAP Group domain name"
},
"email": {
"type": "string",
"description": "LDAP Group email"
},
"description": {
"type": "string",
"description": "LDAP Group description"
}
}
},
"LdapGroup": {
"description": "Class LdapGroup",
"required": [
"id",
"name"
],
"properties": {
"id": {
"description": "LDAP group unique identifier",
"type": "integer"
},
"name": {
"description": "Display name of the LDAP group",
"type": "string"
},
"email": {
"description": "LDAP group email address",
"type": "string"
},
"description": {
"description": "LDAP group description",
"type": "string"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"SourceContent": {
"description": "Class SourceContent - if you need true EAPI entity use App\\Entity\\ECObject",
"required": [
"id",
"name",
"parentId",
"type",
"wopiapp"
],
"properties": {
"id": {
"description": "Unique SourceContent identifier",
"type": "string"
},
"name": {
"description": "Display name of the source content item",
"type": "string"
},
"parentId": {
"description": "Parent source content unique identifier",
"type": "string"
},
"type": {
"description": "Source content type. Accepted values: \\`d\\` (folder), \\`f\\` (file)",
"type": "string"
},
"created": {
"description": "Creation timestamp of the source content in UTC",
"type": "string",
"format": "date"
},
"modified": {
"description": "Last modification timestamp of the source content in UTC",
"type": "string",
"format": "date"
},
"status": {
"description": "Current availability status of the source content item",
"type": "string"
},
"deleted": {
"description": "Indicates whether the source content is deleted",
"type": "boolean"
},
"path": {
"description": "Full path of the source content",
"type": "string"
},
"userRoleId": {
"description": "Current user role id (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "integer"
},
"creator": {
"description": "File's creator (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/UserBasicInfo"
},
"permissions": {
"description": "Current user's permissions (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"wopiapp": {
"description": "WOPI info for iOS app",
"type": "boolean"
},
"rootId": {
"description": "Unique identifier of the root-level source content ancestor (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"pathIds": {
"description": "Ordered list of ancestor identifiers representing the full path from root to this source content item (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"sourceTypeId": {
"description": "Unique identifier of the ECM source type this content belongs to (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"totalFilesCount": {
"description": "Total number of files in the source content (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"totalFoldersCount": {
"description": "Total number of folders in the source content (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"type": "string"
},
"parent": {
"description": "Parent source content item (Explicit field. May be retrieved only if mentioned in \"with\" parameter)",
"$ref": "#/components/schemas/SourceContent"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ErrorString": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
},
"field": {
"type": "string",
"description": "Associated field, if applicable."
},
"failedIds": {
"type": "array",
"description": "List of failed IDs.",
"items": {
"type": "string"
}
}
}
},
"Fingerprint": {
"type": "object",
"properties": {
"algo": {
"type": "string",
"description": "The algorithm used to generate the fingerprint (e.g., sha3-256, md5)."
},
"hash": {
"type": "string",
"description": "The resulting hash value representing the fingerprint of the file or object."
}
}
},
"PushedObject": {
"type": "object",
"properties": {
"objectId": {
"type": "string",
"description": "Unique identifier (UUID) for the pushed object."
},
"userId": {
"type": "string",
"description": "Unique identifier (UUID) for the user who pushed the object."
},
"created": {
"type": "string",
"format": "date",
"description": "The date and time when the object was pushed."
},
"user": {
"description": "Details of the user who pushed the object.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
}
}
},
"MobileInfo": {
"type": "object",
"properties": {
"wopiSrc": {
"type": "string",
"description": "The WOPI (Web Application Open Platform Interface) source URL for the mobile application."
},
"userId": {
"type": "string",
"description": "Unique identifier of the user."
},
"service": {
"type": "string",
"description": "The WOPI service ID."
},
"scheme": {
"type": "string",
"description": "URI scheme used by the mobile application to handle the file."
},
"schemeSupport": {
"type": "string",
"description": "Indicates the level of support the mobile app has for the URI scheme."
}
}
},
"SafeEdit": {
"type": "object",
"properties": {
"safeEditLocked": {
"type": "boolean",
"description": "Indicates if the file is locked through a SafeEdit session."
},
"user": {
"description": "The user responsible for locking the file via SafeEdit.",
"allOf": [
{
"$ref": "#/components/schemas/UserBasic"
}
]
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
}
}
}
}