Kiteworks favorites API
The favorites API from Kiteworks — 3 operation(s) for favorites.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities favorites API
tags:
- name: favorites
paths:
/rest/favorites:
post:
tags:
- favorites
summary: Add a favorite
description: Marks the specified folder as a favorite for the current user.
responses:
'200':
description: Favorite created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Favorite'
examples:
FavoriteCreated:
summary: A newly created favorite
value:
id: 42
objectId: f0e1d2c3-b4a5-6789-0fed-cba987654321
userId: u1a2b3c4-d5e6-7890-abcd-ef1234567890
'409':
description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_EXISTS:
summary: Entity exists
description: Entity exists
value:
errors:
code: ERR_ENTITY_EXISTS
message: Entity exists
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: query
name: returnEntity
description: If set to `true`, returns information about the newly created entity.
schema:
type: boolean
- in: query
name: 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/Favorite.Post'
get:
summary: List favorites
description: "### Description:\n Returns the list of favorites for the current user.\n### Precondition:\n User must be authenticated.\n### Response:\n The list of favorited files and folders is returned.\n"
tags:
- favorites
parameters:
- in: query
name: returnEntity
required: false
description: If true, includes the entity in the response body.
schema:
type: boolean
- in: query
name: with
required: false
description: Specifies additional fields to include in the response.
schema:
type: string
- in: query
name: mode
required: false
description: Determines the detail level of the response body.
schema:
type: string
enum:
- compact
- full_no_links
- full_with_links
- full
- in: query
name: parentId
required: false
description: Filter favorites by parent folder ID.
schema:
type: string
- in: query
name: parentId:in
required: false
explode: true
style: form
description: Filter favorites by parent folder ID. Search for results that contain any of the specified values.
schema:
type: array
items:
type: string
- in: query
name: excludeEc
required: false
description: If set to `true`, excludes Repositories Gateway folders from the results.
schema:
type: boolean
- in: query
name: orderBy
required: false
description: 'Sort order for the results. Default is `objects.created:asc`.<br>Allowed values: `objects.name:asc`, `objects.name:desc`, `objects.created:asc`, `objects.created:desc`, `objects.modified:asc`, `objects.modified:desc`.'
schema:
type: string
enum:
- objects.name:asc
- objects.name:desc
- objects.created:asc
- objects.created:desc
- objects.modified:asc
- objects.modified:desc
- in: query
name: limit
required: false
description: Range limit.
schema:
type: integer
minimum: 1
- in: query
name: offset
required: false
description: Range offset.
schema:
type: integer
minimum: 0
responses:
'200':
description: The list of favorites has been successfully returned.
content:
application/json:
schema:
$ref: '#/components/schemas/FavoriteListOpenAPI2'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_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_DENIED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_DENIED:
summary: Your access is denied.
description: Your access is denied.
value:
errors:
- code: ERR_ACCESS_DENIED
message: Your access is denied.
redirectUrl: /login?code=3317
'490':
description: Request blocked by WAF
/rest/favorites/{id}:
delete:
tags:
- favorites
summary: Remove a favorite
description: Removes the specified favorite from the current user's favorites list.
responses:
'204':
description: Favorite removed successfully.
'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: id
description: ID of the favorite to be removed
required: true
schema:
type: integer
/rest/folders/actions/favorite:
post:
tags:
- favorites
summary: Set multiple folders as favorite
description: Marks multiple folders as favorites for the current user in a single request. Supports partial success, meaning valid items are processed even if some fail.
responses:
'200':
description: Favorites created successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Favorite'
metadata:
$ref: '#/components/schemas/MetaData'
examples:
BulkFavoriteCreated:
summary: Newly created favorites for multiple folders
value:
data:
- id: 42
objectId: f0e1d2c3-b4a5-6789-0fed-cba987654321
userId: u1a2b3c4-d5e6-7890-abcd-ef1234567890
- id: 43
objectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
userId: u1a2b3c4-d5e6-7890-abcd-ef1234567890
'409':
description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_EXISTS:
summary: Entity exists
description: Entity exists
value:
errors:
code: ERR_ENTITY_EXISTS
message: Entity exists
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: query
name: id:in
description: A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed.
required: true
schema:
type: string
- in: query
name: partialSuccess
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
- in: query
name: returnEntity
description: If set to `true`, returns information about the newly created entity.
schema:
type: boolean
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
delete:
tags:
- favorites
summary: Removes specified folders from favorites
description: Removes multiple folders from the current user's favorites list in a single request. Supports partial success, meaning valid items are processed even if some fail.
responses:
'204':
description: Favorites removed successfully.
'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: query
name: id:in
description: A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed.
required: true
schema:
type: string
- in: query
name: partialSuccess
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
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
Errors:
type: object
properties:
error:
type: array
items:
$ref: '#/components/schemas/Error'
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
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.
FavoriteListOpenAPI2:
type: object
properties:
data:
description: List of favorite entries.
type: array
items:
$ref: '#/components/schemas/FavoriteOpenAPI2'
metadata:
description: Pagination metadata for the result set.
allOf:
- $ref: '#/components/schemas/MetaData'
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
Favorite:
description: Class Favorite
required:
- id
- objectId
- userId
properties:
id:
description: Unique identifier of Favorite
type: integer
objectId:
description: Unique identifier of the favorited folder or file
type: string
userId:
description: Unique identifier of the user who created this favorite
type: string
creator:
description: User who created this favorite (Explicit field. May be retrieved only if mentioned in "with" parameter)
$ref: '#/components/schemas/UserBasicInfo'
object:
description: Favorited folder object (Explicit field. May be retrieved only if mentioned in "with" parameter)
$ref: '#/components/schemas/Folder'
links:
description: HATEOAS links associated with the entity
type: array
items:
type: string
Favorite.Post:
description: Class Favorite
required:
- objectId
properties:
objectId:
description: Unique identifier of the favorited folder or file
type: integer
addLinks:
description: Indicates whether HATEOAS links should be included in the response
type: boolean
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
Folder1:
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.
parent:
description: The parent folder of the current folder.
allOf:
- $ref: '#/components/schemas/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
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
FavoriteOpenAPI2:
type: object
properties:
id:
type: integer
description: Unique identifier of the favorite entry.
userId:
type: string
objectId:
type: string
format: uuid
description: Unique identifier (UUID) of the favorited object.
object:
description: Details of the favorited object (folder or external content folder).
allOf:
- $ref: '#/components/schemas/Folder1'
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).
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.