{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — uploads Operations"
},
"paths": {
"/rest/uploads": {
"get": {
"tags": [
"uploads"
],
"summary": "Retrieve all user upload sessions",
"description": "Returns all active (not yet completed) upload sessions associated with the authenticated user. Each record includes the session ID, file name, total and uploaded sizes, chunk counts, and upload URI.",
"responses": {
"200": {
"description": "Upload sessions retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Upload"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"UploadSessionList": {
"summary": "List of active upload sessions",
"value": {
"data": [
{
"id": 101,
"userId": 42,
"timestamp": "2024-03-01T10:00:00+00:00",
"uploadedSize": 1048576,
"uploadedChunks": 1,
"error": null,
"finished": false,
"fileUrl": null
}
],
"metadata": {
"total": 1,
"limit": 50,
"offset": 0
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"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/uploads\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/uploads\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/uploads/config": {
"get": {
"tags": [
"uploads"
],
"summary": "Get upload server configuration",
"description": "Returns the configuration of the upload server, including its active status and the maximum allowed chunk size.",
"responses": {
"200": {
"description": "Upload server configuration retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcfsConfig"
},
"examples": {
"AcfsConfigInfo": {
"summary": "Upload server configuration",
"value": {
"active": 1,
"uploadChunkMax": 10485760
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/uploads/config\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/uploads/config\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/uploads/{id}": {
"get": {
"tags": [
"uploads"
],
"summary": "Get upload session",
"description": "Returns the details of the specified upload session, including its progress, file size, chunk counts, and upload URI.",
"responses": {
"200": {
"description": "Upload session details retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
},
"examples": {
"UploadSessionInfo": {
"summary": "Details of a single upload session",
"value": {
"id": 101,
"userId": 42,
"timestamp": "2024-03-01T10:00:00+00:00",
"uploadedSize": 1048576,
"uploadedChunks": 1,
"error": null,
"finished": false,
"fileUrl": null
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the upload session",
"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/uploads/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the upload session\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/uploads/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"delete": {
"tags": [
"uploads"
],
"summary": "Terminate upload session",
"description": "Terminates the specified upload session and discards any uploaded chunks. If the session resides on a different upload node, the termination request is forwarded to that node.",
"responses": {
"204": {
"description": "Upload session terminated successfully."
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the upload session.",
"required": true,
"schema": {
"type": "integer"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/uploads/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the upload session.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/uploads/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/folders/{id}/actions/initiateUpload/zip": {
"post": {
"summary": "Initiate a ZIP archive upload session for a folder",
"description": "### Description:\n Creates an upload session for a ZIP archive to be uploaded to the specified folder. The archive will be automatically extracted after all chunks are received. Once the session is created, an upload link is returned which can be used to upload the archive in chunks.\n### Precondition:\n The user must have `file_add` permission for the folder.\n### Response:\n The upload session is created and an upload link is returned for subsequent chunk uploads.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateUploadZipPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload session successfully created and an upload link returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_RESTRICTED_EXTENSION, 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_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_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_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_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_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE, ERR_INPUT_INVALID_FORMAT, ERR_INPUT_MAX_VALUE, ERR_INPUT_MIN_VALUE, ERR_INVALID_PARAMETER, ERR_SYSTEM_NO_STORAGE_AVAILABLE, ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_INVALID_DATE": {
"summary": "The input is not a valid date.",
"description": "The input is not a valid date.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
},
"ERR_INPUT_INVALID_FORMAT": {
"summary": "The input is invalid.",
"description": "The input is invalid.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_FORMAT",
"message": "The input is invalid."
}
]
}
},
"ERR_INPUT_MAX_VALUE": {
"summary": "The specified input exceed the maximum allowed value.",
"description": "The specified input exceed the maximum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MAX_VALUE",
"message": "The specified input exceed the maximum allowed value."
}
]
}
},
"ERR_INPUT_MIN_VALUE": {
"summary": "The specified input below the minimum allowed value.",
"description": "The specified input below the minimum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MIN_VALUE",
"message": "The specified input below the minimum allowed value."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"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."
}
]
}
},
"ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS": {
"summary": "No available storage hosts",
"description": "No available storage hosts",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"message": "No available storage hosts"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/folders/:id/actions/initiateUpload/zip\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\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/folders/{id}/actions/initiateUpload/zip\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/folders/{id}/actions/initiateUpload": {
"post": {
"summary": "Initiate a file upload session for a folder",
"description": "### Description:\n Creates an upload session for a file to be added to the specified folder. Once the session is created, an upload link is returned which can be used to upload the file in chunks.\n### Precondition:\n The user must have `file_add` permission for the folder.\n### Response:\n The upload session is created and an upload link is returned for subsequent chunk uploads.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateUploadPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload session successfully created and an upload link returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_RESTRICTED_EXTENSION, 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_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_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_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_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_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE, ERR_INPUT_INVALID_FORMAT, ERR_INPUT_MAX_VALUE, ERR_INPUT_MIN_VALUE, ERR_INVALID_PARAMETER, ERR_SYSTEM_NO_STORAGE_AVAILABLE, ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_INVALID_DATE": {
"summary": "The input is not a valid date.",
"description": "The input is not a valid date.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
},
"ERR_INPUT_INVALID_FORMAT": {
"summary": "The input is invalid.",
"description": "The input is invalid.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_FORMAT",
"message": "The input is invalid."
}
]
}
},
"ERR_INPUT_MAX_VALUE": {
"summary": "The specified input exceed the maximum allowed value.",
"description": "The specified input exceed the maximum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MAX_VALUE",
"message": "The specified input exceed the maximum allowed value."
}
]
}
},
"ERR_INPUT_MIN_VALUE": {
"summary": "The specified input below the minimum allowed value.",
"description": "The specified input below the minimum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MIN_VALUE",
"message": "The specified input below the minimum allowed value."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"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."
}
]
}
},
"ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS": {
"summary": "No available storage hosts",
"description": "No available storage hosts",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"message": "No available storage hosts"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/folders/:id/actions/initiateUpload\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\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/folders/{id}/actions/initiateUpload\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/requestFile/{ref}/actions/initiateUpload": {
"post": {
"summary": "Initiate a file upload session for a request file",
"description": "### Description:\n Creates an upload session for a file to be uploaded to a request file. Once the session is created, an upload link is returned which can be used to upload the file in chunks.\n### Precondition:\n The caller must have access to the request file for uploading.\n### Response:\n The upload session is created and an upload link is returned for subsequent chunk uploads.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "ref",
"required": true,
"description": "The unique reference of the Request File upload link.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateUploadPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload session successfully created and an upload link returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_REQUEST_FILE_UPLOAD_LIMIT_REACHED, ERR_ENTITY_RESTRICTED_EXTENSION",
"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_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_REQUEST_FILE_UPLOAD_LIMIT_REACHED": {
"summary": "Upload limit has reached.",
"description": "Upload limit has reached.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_REQUEST_FILE_UPLOAD_LIMIT_REACHED",
"message": "Upload limit has reached."
}
]
}
},
"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"
}
]
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE, ERR_INPUT_INVALID_FORMAT, ERR_INPUT_MAX_VALUE, ERR_INPUT_MIN_VALUE, ERR_INVALID_PARAMETER, ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_INVALID_DATE": {
"summary": "The input is not a valid date.",
"description": "The input is not a valid date.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
},
"ERR_INPUT_INVALID_FORMAT": {
"summary": "The input is invalid.",
"description": "The input is invalid.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_FORMAT",
"message": "The input is invalid."
}
]
}
},
"ERR_INPUT_MAX_VALUE": {
"summary": "The specified input exceed the maximum allowed value.",
"description": "The specified input exceed the maximum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MAX_VALUE",
"message": "The specified input exceed the maximum allowed value."
}
]
}
},
"ERR_INPUT_MIN_VALUE": {
"summary": "The specified input below the minimum allowed value.",
"description": "The specified input below the minimum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MIN_VALUE",
"message": "The specified input below the minimum allowed value."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS": {
"summary": "No available storage hosts",
"description": "No available storage hosts",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"message": "No available storage hosts"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/requestFile/:ref/actions/initiateUpload\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"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/initiateUpload\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/mail/{id}/actions/initiateUpload": {
"post": {
"summary": "Initiate a file upload session for an email attachment",
"description": "### Description:\n Creates an upload session for a file to be attached to an email. Once the session is created, an upload link is returned which can be used to upload the attachment in chunks.\n### Precondition:\n The user must be the sender of the email.\n### Response:\n The upload session is created and an upload link is returned for subsequent chunk uploads.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the email.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateUploadPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload session successfully created and an upload link returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_RESTRICTED_EXTENSION",
"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_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_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"
}
]
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE, ERR_INPUT_INVALID_FORMAT, ERR_INPUT_MAX_VALUE, ERR_INPUT_MIN_VALUE, ERR_INVALID_PARAMETER, ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_INVALID_DATE": {
"summary": "The input is not a valid date.",
"description": "The input is not a valid date.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
},
"ERR_INPUT_INVALID_FORMAT": {
"summary": "The input is invalid.",
"description": "The input is invalid.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_FORMAT",
"message": "The input is invalid."
}
]
}
},
"ERR_INPUT_MAX_VALUE": {
"summary": "The specified input exceed the maximum allowed value.",
"description": "The specified input exceed the maximum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MAX_VALUE",
"message": "The specified input exceed the maximum allowed value."
}
]
}
},
"ERR_INPUT_MIN_VALUE": {
"summary": "The specified input below the minimum allowed value.",
"description": "The specified input below the minimum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MIN_VALUE",
"message": "The specified input below the minimum allowed value."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS": {
"summary": "No available storage hosts",
"description": "No available storage hosts",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"message": "No available storage hosts"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/mail/:id/actions/initiateUpload\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the email.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/mail/{id}/actions/initiateUpload\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/public/mail/{id}/actions/initiateUpload": {
"post": {
"summary": "Initiate an unauthenticated file upload session for an email attachment",
"description": "### Description:\n Creates an upload session for a file to be attached to an email, without requiring full authentication. Once the session is created, an upload link is returned which can be used to upload the attachment in chunks.\n### Precondition:\n The caller must have a valid unauthenticated access context for the specified email.\n### Response:\n The upload session is created and an upload link is returned for subsequent chunk uploads.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the email.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateUploadPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload session successfully created and an upload link returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_RESTRICTED_EXTENSION",
"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_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_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"
}
]
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE, ERR_INPUT_INVALID_FORMAT, ERR_INPUT_MAX_VALUE, ERR_INPUT_MIN_VALUE, ERR_INVALID_PARAMETER, ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_INVALID_DATE": {
"summary": "The input is not a valid date.",
"description": "The input is not a valid date.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
},
"ERR_INPUT_INVALID_FORMAT": {
"summary": "The input is invalid.",
"description": "The input is invalid.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_FORMAT",
"message": "The input is invalid."
}
]
}
},
"ERR_INPUT_MAX_VALUE": {
"summary": "The specified input exceed the maximum allowed value.",
"description": "The specified input exceed the maximum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MAX_VALUE",
"message": "The specified input exceed the maximum allowed value."
}
]
}
},
"ERR_INPUT_MIN_VALUE": {
"summary": "The specified input below the minimum allowed value.",
"description": "The specified input below the minimum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MIN_VALUE",
"message": "The specified input below the minimum allowed value."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS": {
"summary": "No available storage hosts",
"description": "No available storage hosts",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"message": "No available storage hosts"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/public/mail/:id/actions/initiateUpload\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier (UUID) of the email.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/public/mail/{id}/actions/initiateUpload\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/files/{id}/actions/initiateUpload": {
"post": {
"summary": "Initiate an upload session for a new file version",
"description": "### Description:\n Creates an upload session to add a new version of an existing file. Once the session is created, an upload link is returned which can be used to upload the new version in chunks.\n### Precondition:\n The user must have `version_created` permission for the specified file.\n### Response:\n The upload session is created and an upload link is returned for subsequent chunk uploads.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier (UUID) of the entity.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitiateUploadPostRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload session successfully created and an upload link returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_RESTRICTED_EXTENSION, 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_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_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_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_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_VIRUS_FOUND": {
"summary": "File is infected",
"description": "File is infected",
"value": {
"errors": [
{
"code": "ERR_ENTITY_VIRUS_FOUND",
"message": "File is infected"
}
]
}
}
}
}
}
},
"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."
}
]
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_INVALID_DATE, ERR_INPUT_INVALID_FORMAT, ERR_INPUT_MAX_VALUE, ERR_INPUT_MIN_VALUE, ERR_INVALID_PARAMETER, ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_INVALID_DATE": {
"summary": "The input is not a valid date.",
"description": "The input is not a valid date.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
},
"ERR_INPUT_INVALID_FORMAT": {
"summary": "The input is invalid.",
"description": "The input is invalid.",
"value": {
"errors": [
{
"code": "ERR_INPUT_INVALID_FORMAT",
"message": "The input is invalid."
}
]
}
},
"ERR_INPUT_MAX_VALUE": {
"summary": "The specified input exceed the maximum allowed value.",
"description": "The specified input exceed the maximum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MAX_VALUE",
"message": "The specified input exceed the maximum allowed value."
}
]
}
},
"ERR_INPUT_MIN_VALUE": {
"summary": "The specified input below the minimum allowed value.",
"description": "The specified input below the minimum allowed value.",
"value": {
"errors": [
{
"code": "ERR_INPUT_MIN_VALUE",
"message": "The specified input below the minimum allowed value."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS": {
"summary": "No available storage hosts",
"description": "No available storage hosts",
"value": {
"errors": [
{
"code": "ERR_SYSTEM_NO_AVAILABLE_STORAGE_HOSTS",
"message": "No available storage hosts"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/files/:id/actions/initiateUpload\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\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}/actions/initiateUpload\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"filename\": \"string\",\n \"totalSize\": 1,\n \"totalChunks\": 1,\n \"clientCreated\": \"2024-01-15\",\n \"clientModified\": \"2024-01-15\",\n \"proximateHost\": \"string\"\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/{host_name}/rest/uploads/{id}": {
"post": {
"summary": "Upload a file chunk",
"description": "### Description:\n Uploads a single chunk of a file to the server using the upload link obtained from an initiate-upload call. The file is reconstructed server-side once all chunks are received.\n### Precondition:\n * The caller must hold a valid upload link.\n * The client must split the file into chunks before uploading.\n * Chunks must be uploaded sequentially, starting from index 1.\n### Response:\n Returns the updated upload session after each intermediate chunk, and the completed file record after the final chunk.\n",
"tags": [
"uploads"
],
"parameters": [
{
"in": "path",
"name": "host_name",
"required": true,
"description": "The upload host name, which can be retrieved from GET /uploads/{id} or the initiateUpload response.",
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier of the upload.",
"schema": {
"type": "integer"
}
},
{
"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": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"compressionMode": {
"type": "string",
"description": "The compression mode used for the chunk. Options include \"NORMAL\", \"GZIP\", and \"ZLIB\".",
"enum": [
"NORMAL",
"GZIP",
"ZLIB"
]
},
"compressionSize": {
"type": "integer",
"format": "int64",
"description": "The size of the chunk after compression."
},
"originalSize": {
"type": "integer",
"format": "int64",
"description": "The size of the chunk before compression."
},
"content": {
"type": "string",
"format": "binary",
"description": "The binary content of the chunk."
},
"index": {
"type": "integer",
"format": "int64",
"description": "The sequential index of the chunk (starts from 1)."
},
"lastChunk": {
"type": "integer",
"format": "int64",
"description": "Indicates if this is the last chunk of the file (1 if last, 0 otherwise)."
}
},
"required": [
"compressionMode",
"compressionSize",
"originalSize",
"content"
]
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BaseChunkUploadRequest"
}
}
}
},
"responses": {
"200": {
"description": "The current chunk upload is successfully received but not yet registered to the server.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Upload"
}
}
}
},
"201": {
"description": "File uploaded successfully and is registered to the server after the last chunk is received.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/File"
}
}
}
},
"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_ACCESS_USER, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_REQUEST_FILE_UPLOAD_LIMIT_REACHED, ERR_ENTITY_RESTRICTED_TYPE, 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_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_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_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_REQUEST_FILE_UPLOAD_LIMIT_REACHED": {
"summary": "Upload limit has reached.",
"description": "Upload limit has reached.",
"value": {
"errors": [
{
"code": "ERR_ENTITY_REQUEST_FILE_UPLOAD_LIMIT_REACHED",
"message": "Upload limit has reached."
}
]
}
},
"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_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_NOT_IN_LIST, ERR_INVALID_PARAMETER, ERR_LICENSE_MAX_UPLOAD_SIZE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_NOT_IN_LIST": {
"summary": "The specified input is not allowed.",
"description": "The specified input is not allowed.",
"value": {
"errors": [
{
"code": "ERR_INPUT_NOT_IN_LIST",
"message": "The specified input is not allowed."
}
]
}
},
"ERR_INVALID_PARAMETER": {
"summary": "Invalid Parameter Exception",
"description": "Invalid Parameter Exception",
"value": {
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
},
"ERR_LICENSE_MAX_UPLOAD_SIZE": {
"summary": "Upload size exceed licensed maximum upload size",
"description": "Upload size exceed licensed maximum upload size",
"value": {
"errors": [
{
"code": "ERR_LICENSE_MAX_UPLOAD_SIZE",
"message": "Upload size exceed licensed maximum upload size"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/:host_name/rest/uploads/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"compressionMode\": \"NORMAL\",\n \"compressionSize\": 1,\n \"content\": \"string\",\n \"originalSize\": 1,\n \"index\": 1,\n \"lastChunk\": 1\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nhost_name = \"VALUE\" # The upload host name, which can be retrieved from GET /uploads/{id} or the initiateUpload response.\nid = \"VALUE\" # The unique identifier of the upload.\n\nurl = f\"https://{{instance}}.kiteworks.com/{host_name}/rest/uploads/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"compressionMode\": \"NORMAL\",\n \"compressionSize\": 1,\n \"content\": \"string\",\n \"originalSize\": 1,\n \"index\": 1,\n \"lastChunk\": 1\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"Upload": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the upload."
},
"userId": {
"type": "string",
"description": "Unique identifier of the user who initiated the upload."
},
"timestamp": {
"type": "string",
"format": "date",
"description": "Timestamp when the upload was initiated."
},
"totalSize": {
"type": "integer",
"description": "Total size of the uploaded file in bytes."
},
"totalChunks": {
"type": "integer",
"description": "Total number of chunks the file was split into."
},
"clientName": {
"type": "string",
"description": "Name of the client uploading the file."
},
"svrUploadTime": {
"type": "integer",
"description": "Time taken by the server to process the upload (in milliseconds)."
},
"uploadedSize": {
"type": "integer",
"description": "Total size of the uploaded chunks in bytes."
},
"lastTimestamp": {
"type": "string",
"format": "date",
"description": "Timestamp of the last uploaded chunk."
},
"error": {
"type": "string",
"description": "Error message in case of upload failure."
},
"uri": {
"readOnly": true,
"description": "The URI for the upload link."
},
"completeOk": {
"type": "integer",
"description": "Flag indicating if the upload was completed successfully (1 for success, 0 otherwise)."
},
"fileUrl": {
"type": "string",
"description": "URL where the uploaded file can be accessed."
},
"replaceId": {
"type": "string",
"description": "ID of the file being replaced, if applicable."
},
"backend": {
"type": "string",
"description": "Backend storage system used for the upload."
},
"finished": {
"type": "boolean",
"description": "Indicates whether the upload process has finished."
},
"clientCreated": {
"type": "string",
"format": "date",
"description": "Timestamp when the file was created on the client side."
},
"clientModified": {
"type": "string",
"format": "date",
"description": "Timestamp when the file was last modified on the client side."
},
"requestFileId": {
"type": "integer",
"description": "ID of the file request associated with the upload."
},
"emailId": {
"type": "integer",
"description": "ID of the email associated with the uploaded file, if applicable."
},
"uploadedChunks": {
"type": "integer",
"description": "Number of chunks successfully uploaded."
},
"location": {
"type": "string",
"description": "The logical storage location of the uploaded file."
},
"uploadUrl": {
"readOnly": true,
"description": "The complete URL for the upload link."
}
}
},
"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."
}
}
},
"AcfsConfig": {
"description": "Class AcfsConfig",
"properties": {
"acfsDbname": {
"description": "ACFS database name",
"type": "string"
},
"active": {
"description": "Indicates whether the upload server is active",
"type": "integer"
},
"message": {
"description": "ACFS status message",
"type": "string"
},
"minReplication": {
"description": "Minimum replication factor required for data stored on this ACFS node",
"type": "string"
},
"uploadChunkMax": {
"description": "Maximum size of a single upload chunk in bytes",
"type": "integer"
},
"uploadTimeout": {
"description": "Upload timeout in seconds",
"type": "integer"
},
"uploadWipe": {
"description": "Indicates whether uploaded data is wiped from temporary storage after processing",
"type": "integer"
}
}
},
"InitiateUploadZipPostRequest": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Name of the file to be uploaded."
},
"totalSize": {
"type": "integer",
"description": "Total size of the file to be uploaded, in bytes."
},
"totalChunks": {
"type": "integer",
"minimum": 1,
"description": "Total number of chunks the file will be split into. Must be at least 1."
},
"clientCreated": {
"type": "string",
"format": "date",
"description": "File creation timestamp as reported by the client (e.g. from the OS or browser)."
},
"clientModified": {
"type": "string",
"format": "date",
"description": "File last-modified timestamp as reported by the client (e.g. from the OS or browser)."
},
"proximateHost": {
"type": "string",
"description": "Proximate hostname used to direct client uploads to the nearest available storage endpoint."
},
"tracking_id": {
"type": "string",
"format": "uuid",
"description": "Tracking ID for correlating the upload with an external transfer"
},
"resume": {
"type": "boolean",
"description": "Indicates whether this is a resumption of a previously interrupted upload. Only applicable when a file with the same name already exists. Currently used internally for SFTP transfers only."
},
"uncompressedSize": {
"type": "integer",
"description": "Total uncompressed size of the archive file, in bytes."
}
},
"required": [
"filename",
"uncompressedSize"
]
},
"Errors": {
"type": "object",
"properties": {
"error": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"InitiateUploadPostRequest": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Name of the file to be uploaded."
},
"totalSize": {
"type": "integer",
"description": "Total size of the file to be uploaded, in bytes."
},
"totalChunks": {
"type": "integer",
"minimum": 1,
"description": "Total number of chunks the file will be split into. Must be at least 1."
},
"clientCreated": {
"type": "string",
"format": "date",
"description": "File creation timestamp as reported by the client (e.g. from the OS or browser)."
},
"clientModified": {
"type": "string",
"format": "date",
"description": "File last-modified timestamp as reported by the client (e.g. from the OS or browser)."
},
"proximateHost": {
"type": "string",
"description": "Proximate hostname used to direct client uploads to the nearest available storage endpoint."
},
"tracking_id": {
"type": "string",
"format": "uuid",
"description": "Tracking ID for correlating the upload with an external transfer"
},
"resume": {
"type": "boolean",
"description": "Indicates whether this is a resumption of a previously interrupted upload. Only applicable when a file with the same name already exists. Currently used internally for SFTP transfers only."
}
},
"required": [
"filename"
]
},
"BaseChunkUploadRequest": {
"type": "object",
"properties": {
"compressionMode": {
"type": "string",
"enum": [
"NORMAL",
"GZIP",
"ZLIB"
],
"description": "The compression algorithm applied to this chunk.
`NORMAL` – No compression; the chunk is sent as-is.
`GZIP` – Chunk is compressed using GZIP.
`ZLIB` – Chunk is compressed using ZLIB."
},
"compressionSize": {
"type": "integer",
"description": "The size of the chunk after compression."
},
"content": {
"type": "string",
"description": "The content of the chunk. If the request is in JSON format, this will be base64-encoded."
},
"originalSize": {
"type": "integer",
"description": "The original upload content size before compression."
},
"index": {
"type": "integer",
"description": "The sequential index of the chunk (starts from 1)."
},
"lastChunk": {
"type": "integer",
"description": "Indicates if this is the last chunk of the file (1 if last, 0 otherwise)."
}
},
"required": [
"compressionMode",
"compressionSize",
"content",
"originalSize"
]
},
"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."
}
}
},
"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."
}
}
},
"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)."
}
}
},
"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
}
}
},
"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."
}
}
},
"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"
}
}
},
"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."
}
}
},
"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."
}
}
},
"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"
}
]
}
}
},
"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"
}
}
},
"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"
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
}
}
}
}