Kiteworks comments API
The comments API from Kiteworks — 4 operation(s) for comments.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities comments API
tags:
- name: comments
paths:
/rest/comments/{id}:
get:
tags:
- comments
summary: Get a comment
description: Returns the details of the specified comment, including the file it is attached to and the comment text. **Requires `comment_view` permission on the associated file.**
responses:
'200':
description: Returns the comment record.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
examples:
Comment:
summary: A single comment record
value:
id: 201
parent_id: 0
object_id: 7
folder_id: 3
user_id: 5
created: '2024-03-15T10:00:00+00:00'
modified: '2024-03-15T10:00:00+00:00'
contents: Please review section 3.
deleted: false
is_comment: true
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: path
name: id
description: The unique identifier of the comment.
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
put:
tags:
- comments
summary: Update a comment
description: Updates the text of the specified comment. **Requires `comment_edit` permission on the associated file.** Only the comment author or a folder manager may update the comment.
responses:
'200':
description: Returns the updated comment record.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
examples:
Comment updated:
summary: An updated comment
value:
id: 201
parent_id: 0
object_id: 7
folder_id: 3
user_id: 5
created: '2024-03-15T10:00:00+00:00'
modified: '2024-03-16T08:00:00+00:00'
contents: Please review section 3 and section 4.
deleted: false
is_comment: true
'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: id
description: The unique identifier of the comment.
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Comment.Put'
delete:
tags:
- comments
summary: Delete a comment
description: Deletes the specified comment. **Requires `comment_delete` permission on the associated file.** Only the comment author or a folder manager may delete the comment.
responses:
'204':
description: The comment was successfully deleted. Returns no content.
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: path
name: id
description: The unique identifier of the comment.
required: true
schema:
type: integer
/rest/files/{id}/comments:
get:
tags:
- comments
summary: Get file comments
description: Returns a list of comments on the specified file. **Requires `comment_view` permission on the file.**
responses:
'200':
description: Returns a paginated list of comments for the specified file.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
metadata:
$ref: '#/components/schemas/MetaData'
examples:
File comment list:
summary: Two comments on a file
value:
data:
- id: 201
parent_id: 0
object_id: 7
folder_id: 3
user_id: 5
created: '2024-03-15T10:00:00+00:00'
modified: '2024-03-15T10:00:00+00:00'
contents: Please review section 3.
deleted: false
is_comment: true
- id: 202
parent_id: 201
object_id: 7
folder_id: 3
user_id: 3
created: '2024-03-15T11:00:00+00:00'
modified: '2024-03-15T11:00:00+00:00'
contents: Done, updated section 3.
deleted: false
is_comment: true
total: 2
page: 1
pageSize: 20
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: path
name: id
description: The unique identifier (UUID) of the file.
required: true
schema:
type: string
- in: query
name: parentId
description: Unique identifier of the parent comment
schema:
type: integer
- in: query
name: parentId:in
description: Unique identifier of the parent comment. Search for results that match any of the specified values for this parameter.
schema:
type: integer
- in: query
name: userId
description: Unique identifier of the comment author
schema:
type: string
- in: query
name: userId:in
description: Unique identifier of the comment author. Search for results that match any of the specified values for this parameter.
schema:
type: string
- in: query
name: created
description: The creation date of the comment.
schema:
type: string
format: date
- in: query
name: created:gt
description: The creation date of the comment.. Search for results where this parameter value is greater than the specified value.
schema:
type: string
format: date
- in: query
name: created:gte
description: The creation date of the comment.. Search for results where this parameter value is greater than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: created:lt
description: The creation date of the comment.. Search for results where this parameter value is less than the specified value.
schema:
type: string
format: date
- in: query
name: created:lte
description: The creation date of the comment.. Search for results where this parameter value is less than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: modified
description: The last modification date of the comment.
schema:
type: string
format: date
- in: query
name: modified:gt
description: The last modification date of the comment.. Search for results where this parameter value is greater than the specified value.
schema:
type: string
format: date
- in: query
name: modified:gte
description: The last modification date of the comment.. Search for results where this parameter value is greater than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: modified:lt
description: The last modification date of the comment.. Search for results where this parameter value is less than the specified value.
schema:
type: string
format: date
- in: query
name: modified:lte
description: The last modification date of the comment.. Search for results where this parameter value is less than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: contents:contains
description: Content of the comment. Search for results that contain the specified characters in this parameter.
schema:
type: string
- in: query
name: orderBy
description: Sorting options
schema:
type: array
items:
type: string
enum:
- id:asc
- id:desc
- created:asc
- created:desc
- modified:asc
- modified:desc
- parentId:asc
- parentId:desc
- in: query
name: offset
description: Offset
schema:
type: integer
- in: query
name: limit
description: Limit
schema:
type: integer
- in: query
name: with
description: With parameters
schema:
type: string
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
- compact
post:
tags:
- comments
summary: Add file comment
description: Adds a comment to the specified file. To reply to an existing comment, include a `parentId` in the request body. **Requires `comment_add` permission on the file.**
responses:
'200':
description: Returns the newly created comment record.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
examples:
Comment created:
summary: A newly created comment on a file
value:
id: 203
parent_id: 0
object_id: 7
folder_id: 3
user_id: 5
created: '2024-03-16T09:00:00+00:00'
modified: '2024-03-16T09:00:00+00:00'
contents: Looks good to me.
deleted: false
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: id
description: The unique identifier (UUID) of the file.
required: true
schema:
type: string
- in: query
name: returnEntity
description: If set to `true`, returns information about the newly created entity.
schema:
type: boolean
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Comment.Post'
/rest/folders/{id}/comments:
get:
tags:
- comments
summary: List comments for the folder
description: Returns all comments on files within the specified folder. **Requires `comment_view` permission on the folder.**
responses:
'200':
description: Returns a paginated list of comments for files within the specified folder.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
metadata:
$ref: '#/components/schemas/MetaData'
examples:
Folder comment list:
summary: Two comments on files in a folder
value:
data:
- id: 201
parent_id: 0
object_id: 7
folder_id: 3
user_id: 5
created: '2024-03-15T10:00:00+00:00'
modified: '2024-03-15T10:00:00+00:00'
contents: Please review section 3.
deleted: false
is_comment: true
- id: 202
parent_id: 201
object_id: 7
folder_id: 3
user_id: 3
created: '2024-03-15T11:00:00+00:00'
modified: '2024-03-15T11:00:00+00:00'
contents: Done, updated section 3.
deleted: false
is_comment: true
total: 2
page: 1
pageSize: 20
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: path
name: id
description: The unique identifier (UUID) of the folder.
required: true
schema:
type: string
- in: query
name: parentId
description: Unique identifier of the parent comment
schema:
type: integer
- in: query
name: parentId:in
description: Unique identifier of the parent comment. Search for results that match any of the specified values for this parameter.
schema:
type: integer
- in: query
name: userId
description: Unique identifier of the comment author
schema:
type: string
- in: query
name: userId:in
description: Unique identifier of the comment author. Search for results that match any of the specified values for this parameter.
schema:
type: string
- in: query
name: created
description: The creation date of the comment.
schema:
type: string
format: date
- in: query
name: created:gt
description: The creation date of the comment.. Search for results where this parameter value is greater than the specified value.
schema:
type: string
format: date
- in: query
name: created:gte
description: The creation date of the comment.. Search for results where this parameter value is greater than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: created:lt
description: The creation date of the comment.. Search for results where this parameter value is less than the specified value.
schema:
type: string
format: date
- in: query
name: created:lte
description: The creation date of the comment.. Search for results where this parameter value is less than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: modified
description: The last modification date of the comment.
schema:
type: string
format: date
- in: query
name: modified:gt
description: The last modification date of the comment.. Search for results where this parameter value is greater than the specified value.
schema:
type: string
format: date
- in: query
name: modified:gte
description: The last modification date of the comment.. Search for results where this parameter value is greater than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: modified:lt
description: The last modification date of the comment.. Search for results where this parameter value is less than the specified value.
schema:
type: string
format: date
- in: query
name: modified:lte
description: The last modification date of the comment.. Search for results where this parameter value is less than or equal to the specified value.
schema:
type: string
format: date
- in: query
name: contents:contains
description: Content of the comment. Search for results that contain the specified characters in this parameter.
schema:
type: string
- in: query
name: orderBy
description: Sorting options
schema:
type: array
items:
type: string
enum:
- id:asc
- id:desc
- created:asc
- created:desc
- modified:asc
- modified:desc
- parentId:asc
- parentId:desc
- in: query
name: offset
description: Offset
schema:
type: integer
- in: query
name: limit
description: Limit
schema:
type: integer
- in: query
name: with
description: With parameters
schema:
type: string
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
- compact
/rest/permissions/comment/{comment_id}:
get:
tags:
- comments
summary: Return the list of permissions available on a comment
description: Returns the list of actions the current user is allowed to perform on the specified comment, such as editing or deleting it.
responses:
'200':
description: Comment permissions retrieved successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Permission'
examples:
CommentPermissions:
summary: Permissions available on a comment
value:
data:
- id: COMMENT_EDIT
name: Edit Comment
allowed: true
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: path
name: comment_id
description: ID of the comment
required: true
schema:
type: integer
- in: query
name: id
description: Unique action identifier
schema:
type: integer
- in: query
name: id:in
description: Unique action identifier. Search for results that match any of the specified values for this parameter.
schema:
type: integer
- in: query
name: name
description: Action name
schema:
type: string
- in: query
name: name:contains
description: Action name. Search for results that contain the specified characters in this parameter.
schema:
type: string
- in: query
name: allowed
description: Determines if one has permissions to perform action
schema:
type: boolean
- in: query
name: enabled
description: Determines if the given action is available considering the current object state (locked, deleted, etc.).
schema:
type: boolean
- in: query
name: with
description: With parameters
schema:
type: string
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
- compact
components:
schemas:
UserBasicInfo:
required:
- email
- id
- name
properties:
id:
description: The unique identifier of the user
type: string
name:
description: The name of the user
type: string
email:
description: The user's email
type: string
profileIcon:
description: URL to the user's profile icon image
type: string
Comment.Put:
description: Class Comment
required:
- contents
properties:
contents:
description: Text content of the comment
type: string
addLinks:
description: Indicates whether HATEOAS links should be included in the response
type: boolean
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
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.<br>`f` – File.<br>`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
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.
Errors:
type: object
properties:
error:
type: array
items:
$ref: '#/components/schemas/Error'
Error:
type: object
properties:
code:
type: string
description: Error code
message:
type: string
description: Error message
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
Comment.Post:
description: Class Comment
required:
- contents
properties:
parentId:
description: Unique identifier of the parent comment. Set this value when replying to an existing comment
type: integer
contents:
description: Text content of the
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kiteworks/refs/heads/main/openapi/kiteworks-comments-api-openapi.yml