Kiteworks requestFile API
The requestFile API from Kiteworks — 13 operation(s) for requestfile.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities requestFile API
tags:
- name: requestFile
paths:
/rest/folders/{id}/actions/requestFile:
post:
summary: Send a Request File to Folder request
description: "### Description:\n Initiates a Request File to Folder.\n### Precondition:\n The user profile must have the necessary access rights to request files to the folder.\n### Response:\n Successfully creates a request file and returns the request file details.\n"
tags:
- requestFile
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/RequestFileToFolderPostRequest'
responses:
'201':
description: Request File to Folder request has been successfully created.
'400':
description: 'Bad Request<br /><br /><i>Possible error codes: </i>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<br /><br /><i>Possible error codes: </i>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<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_DLP_LOCKED, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_NOT_SCANNED, ERR_ENTITY_VIRUS_FOUND, ERR_INPUT_EMAIL_IS_DISTRIBUTION_LIST, ERR_LICENSE_MAX_USERS_COUNT_REACHED, ERR_USER_HAS_NO_USER_TYPE, ERR_USER_TYPE_NO_ACCESS'
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
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_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
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_HYPERLINK, ERR_INPUT_INVALID_DATE, ERR_INPUT_REQUIRED, ERR_INVALID_PARAMETER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_HYPERLINK:
summary: Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain.
description: Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain.
value:
errors:
- code: ERR_INPUT_HYPERLINK
message: Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain.
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_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
- code: ERR_INPUT_REQUIRED
message: Field is required
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
/rest/requestFile/{ref}:
delete:
tags:
- requestFile
summary: Expire a request file link
description: Marks the request file link as expired, preventing any further file uploads through it. **Requires the authenticated user to be the user who created the request file link.**
responses:
'204':
description: The request file link was successfully expired. Returns no content.
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>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
get:
summary: Returns Request File Info by ref
description: "### Description:\n Retrieves detailed information about a Request File using the provided reference (ref).\n### Precondition:\n The user must have valid authentication and appropriate access to view the request file information.\n### Response:\n Returns the details of the specified request file, including its associated metadata and status.\n"
tags:
- requestFile
parameters:
- in: path
name: ref
required: true
description: The unique reference of the Request File upload link.
schema:
type: string
- in: query
name: read
required: false
description: Indicates whether to log the view event. Defaults to true.
schema:
type: boolean
responses:
'200':
description: The Request File Info, including the details of the specified request file.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestFile'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_REQUEST_FILE, 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_REQUEST_FILE:
summary: Operation not permitted. This request requires authorization
description: Operation not permitted. This request requires authorization
value:
errors:
- code: ERR_AUTH_REQUEST_FILE
message: Operation not permitted. This request requires authorization
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_REQUEST_FILE_EXPIRED'
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_REQUEST_FILE_EXPIRED:
summary: The request file has expired
description: The request file has expired
value:
errors:
- code: ERR_ENTITY_REQUEST_FILE_EXPIRED
message: The request file has expired
'490':
description: Request blocked by WAF
/rest/requestFile/{ref}/actions/file:
post:
tags:
- 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<br /><br /><i>Possible error codes: </i>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<br /><br /><i>Possible error codes: </i>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
/rest/requestFile/{ref}/comment/{object_id}:
post:
tags:
- 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<br /><br /><i>Possible error codes: </i>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<br /><br /><i>Possible error codes: </i>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'
/rest/requestFile/{ref}/preview/{object_id}:
get:
tags:
- requestFile
summary: Get preview metadata for a source file
description: Gets the preview metadata for a source file attached to the request file link. If the source file's action is set to `view`, the preview is generated with the Viewer role.
responses:
'200':
description: Returns the preview metadata for the specified source file.
content:
application/json:
schema:
$ref: '#/components/schemas/Preview'
examples:
Preview ready:
summary: Preview is available for the source file
value:
link: /preview/files/7/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<br /><br /><i>Possible error codes: </i>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 (UUID) of the source file.
required: true
schema:
type: string
/rest/requestFile/{ref}/sources:
get:
tags:
- requestFile
summary: Get source files attached by the requester
description: Returns the list of files the requester attached to the request file link for the uploader to view or download. Each entry includes computed permissions based on DLP policy and the configured action (`view` or `download`).
responses:
'200':
description: Returns a paginated list of source file records attached to the request file link.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RequestFileSource'
metadata:
$ref: '#/components/schemas/MetaData'
examples:
Source file list:
summary: Two source files, one view-only and one downloadable
value:
data:
- id: 1
file_id: 7
requestfile_id: 12
action_id: 1
permissions:
- name: view
enabled: true
- name: download
enabled: false
- id: 2
file_id: 8
requestfile_id: 12
action_id: 2
permissions:
- name: view
enabled: true
- name: download
enabled: true
total: 2
page: 1
pageSize: 20
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>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
/rest/requestFile/{ref}/sources/{object_id}:
get:
tags:
- requestFile
summary: Get source file metadata
description: Gets the file metadata for a specific source file attached to the request file link.
responses:
'200':
description: Returns the file metadata for the specified source file.
content:
application/json:
schema:
$ref: '#/components/schemas/File'
examples:
Source file metadata:
summary: Metadata for a source file attached to the request link
value:
id: 7
name: onboarding-checklist.pdf
parent_id: 3
size: 102400
mime: application/pdf
created: '2024-01-10T09:00:00+00:00'
modified: '2024-03-01T14:30:00+00:00'
deleted: false
locked: 0
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>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 (UUID) of the source 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
/rest/requestFile/{ref}/sources/{object_id}/content:
get:
tags:
- 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<br /><br /><i>Possible error codes: </i>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
/rest/requestFile/{ref}/uploads:
get:
tags:
- requestFile
summary: Get files uploaded by the current user
description: Returns the list of files the currently authenticated user has uploaded for the specified request file link. Returns an empty list when the link does n
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kiteworks/refs/heads/main/openapi/kiteworks-requestfile-api-openapi.yml